Ben's dotfiles

My dotfiles. They've gone through many ups and downs over the years, but at the moment they're:

• text and terminal centric (hx, Rex, yazi)
• cross-platform (macOS and linux)
• designed to work just as well over ssh as run locally

Where I've taken anything from the web I've tried to give credit appropriate to the licence. If I've missed giving you a shout out, then let me know and I'll gladly add one in.

Quick start

Bootstrap a new machine with:

curl -fsSL https://raw.githubusercontent.com/benswift/.dotfiles/main/install.sh | bash

This installs Homebrew and mise, clones the repo, creates symlinks, and installs mise-managed tools.

Installation (manual)

If you prefer to set things up manually:

git clone https://github.com/benswift/.dotfiles.git ~/.dotfiles
~/.dotfiles/create_symlinks.sh

Verification

Check that everything is set up correctly:

dotfiles doctor

Platform support

Works on macOS (Apple Silicon) and Linux. The setup is zsh-only and mise-first for tool management, using Homebrew on macOS and native package managers on Linux.

AI coding agents

This repo provides shared configuration for multiple AI coding agents, with AGENTS.md as the common project-level instructions file.

How each agent uses these files

• Claude Code: claude/CLAUDE.md is symlinked to ~/.claude/CLAUDE.md. claude/settings.json (keys the repo owns) and claude/settings.seed.json (defaults a machine may change) are merged into ~/.claude/settings.json, not linked, so /model and plugin installs never touch the repo.
• Codex CLI: the same global instructions are symlinked to ~/.codex/AGENTS.md, and portable notification hooks are symlinked to ~/.codex/hooks.json. Model selection, project-instruction fallbacks, trusted-project paths and UI state remain machine-local in ~/.codex/config.toml; the oy alias only selects full-access mode.
• Antigravity CLI: the global instructions are also symlinked to ~/.gemini/AGENTS.md. antigravity/settings.json and its seed are merged into ~/.gemini/antigravity-cli/settings.json the same way, and a SessionStart hook (antigravity/hooks.json) injects the CLAUDE.md of a repo that has no AGENTS.md, which agy doesn't read on its own.

The create_symlinks.sh script sets up all necessary symlinks and directories.

Personal skills plugin (ben)

My personal Claude Code skills library (mail, vault, benswift-writer, phdconvenor, etc.) lives in a separate private repo, benswift/claude-plugin-personal, loaded as a Claude Code plugin. The setup:

• Registered via install.sh / dotfiles update using claude plugin marketplace add benswift/claude-plugin-personal and claude plugin install --scope user ben@ben, then enabled in claude/settings.json via enabledPlugins: {"ben@ben": true} --- portable across machines, no hardcoded paths.
• Claude Code clones it to ~/.claude/plugins/marketplaces/ben/ on first use. That clone is read-only: Claude Code re-clones it on every update. Edit, commit and push in the working checkout at ~/projects/claude-plugin-personal instead.
• Codex reads the same personal skills via per-skill symlinks inside ~/.agents/skills, Codex's supported user-level skill directory. Existing independently installed skills in that directory are left alone.
• Skills appear to Claude as ben:<skill-name> (e.g. ben:vault) and to Codex by their unnamespaced skill name.

To propagate changes across machines: push from the working checkout, then run dotfiles update on each machine (this one included). That refreshes Claude plugins and re-syncs Codex skill links. Requires SSH auth to GitHub (the repo is private). The sync skips plugins entirely if claude isn't installed yet, so on a fresh host install Claude Code before running dotfiles update.

Elixir projects tip

The Usage Rules package is excellent for injecting project-specific rules into your AGENTS.md file:

mix usage_rules.sync AGENTS.md --all --inline usage_rules:all --link-to-folder deps --link-style at --remove-missing

Private overlay

Config that names my accounts and machines (mail, backups, some ssh hosts) lives in a separate private repo, cloned into private/ when the machine can read it. Everything here works without it; lib/private.sh lists the hooks.

License

(c) 2012-2025 Ben Swift

MIT License