Dotfiles

Personal dotfiles for macOS (Apple Silicon). Jump to Keybindings for every shortcut this config defines. See CHANGELOG.md for notable changes and CLAUDE.md for architecture and tooling rationale.

git clone git@github.com:itsmeduncan/dotfiles.git
cd dotfiles
./install.sh

• --dry-run — preview every mutating action as [DRY] would: ... without executing
• --check — audit mode: report drift (symlinks, Brewfile, mise, macOS defaults), change nothing
• --skip=a,b / --only=a,b — skip or isolate phases: preflight brew symlinks mise agents runtimes android macos ssh
• --snapshot — write bootstrap-state.snapshot recording current versions of every brew/mise tool, submodule, and plugin

The installer is idempotent and skips already-satisfied work (Brewfile check, nvim lazy-lock hash, tmux plugin dirs).

install.sh is a thin orchestrator over phase modules in lib/:

• brew — install Homebrew if missing, then sync the Brewfile: a slim set of things mise can't manage (tmux, postgresql@18, watchman, zsh plugins, mosh/nmap/wget, tldr, yazi, git-absorb, cocoapods) plus GUI casks (Ghostty, OrbStack, 1Password + CLI, Slack, Notion, Tailscale, LM Studio, gcloud-cli, MesloLGS Nerd Font)
• symlinks — all dotfiles to $HOME; config dirs (nvim, yazi, uv, bat, ghostty, opencode) to ~/.config/; pnpm to ~/Library/Preferences/; bin/ utilities to ~/.dotfiles/bin/
• mise — symlink mise.toml to ~/.config/mise/config.toml, then install everything declared there via mise: all language runtimes (Node, Python, Ruby, Go, Java, Bun) plus most CLI tools (neovim, eza, bat, ripgrep, fd, zoxide, fzf, delta, direnv, gh, lazygit, pre-commit, uv, pnpm, just, jq, yq, hyperfine, dust, bottom, tokei, awscli, terraform, opencode, swiftlint, atuin, pi-coding-agent)
• agents — shared agent skills from agents/skills/ to ~/.claude/skills, ~/.agents/skills, and ~/.pi/agent/skills; Claude Code config to ~/.claude/
• runtimes — oh-my-zsh, Rust via rustup, tpm + tmux plugins, Neovim plugins via lazy.nvim
• android — Android SDK via Homebrew commandlinetools (only when missing)
• macos — productivity defaults (key repeat, Finder, Dock; version-aware, diff-before-write), application firewall
• ssh — generate an ed25519 key if missing (passphrase-protected by default)

• mise.toml pins every runtime and CLI tool version
• .tool-versions (asdf format, runtimes only) is generated from it via bin/sync-tool-versions — CI fails if they drift
• ./install.sh --snapshot writes bootstrap-state.snapshot, a human-diffable record of the last-known-good system state

The tracked gitconfig wires up SSH signing via 1Password's op-ssh-sign but leaves it off — enable per machine in ~/.gitconfig.local (loaded via includeIf, safe if missing):

[user]
    signingKey = ssh-ed25519 AAAA... your-key
[commit]
    gpgsign = true
[tag]
    gpgsign = true

.github/workflows/ci.yml:

• Tier-1 (Ubuntu, every push/PR): bash -n, shellcheck, shfmt, JSON/YAML validation, prettier, gitleaks secret scan, .tool-versions sync check
• Tier-2 (macOS, any pull request or manual workflow_dispatch): ./install.sh --dry-run, then a real end-to-end install on a clean runner, then ./install.sh --check

Pre-commit hooks (.pre-commit-config.yaml) run the same linters locally: pre-commit install once, then they fire on every commit.

Global cross-agent skills live in agents/skills/.

Claude consumes them through claude/skills -> ../agents/skills. Codex discovers them through ~/.agents/skills. OpenCode is configured with skills.paths in config/opencode/opencode.json. Pi gets the same tree at ~/.pi/agent/skills for agents that know to inspect a local skills directory.

Every key combo, alias, and shortcut this config defines, and which file defines it. Bindings below were verified against a live tmux server and the current config files.

The eight you'll reach for most:

Defined in tmux.conf. Prefix is the default C-b — it is not remapped.

Notation: C-b | means press C-b, release, then |. Bindings marked no prefix are pressed directly. -r bindings repeat: hold the prefix once, then tap the key.

| and - replace the default % and ", which are unbound. New splits and windows inherit the current pane's working directory rather than starting at $HOME.

Each opens centered over the current pane and closes on exit.

C-b f and C-b m override tmux's defaults (find-window and mark-pane).

From tmux-pomodoro-plus. Desktop notifications are off by design — the countdown is always visible in the status bar instead, rendered by bin/pomodoro-status, which shows a dim 🍅 -- placeholder when no timer is running.

Plugin defaults are unchanged: 25 min work, 5 min break, 4 intervals, then a 25 min long break.

C-b p overrides tmux's default previous-window. Use C-b M-1…M-5 or C-b n / C-b l to move between windows instead.

vi keys (setw -g mode-keys vi). Enter with C-b [, or just scroll — the mouse is on.

Top-positioned, refreshed every 30s: session name → window tabs → Pomodoro countdown → weather → battery → date/time. The session block turns amber while the prefix is armed, so you can see whether C-b registered. Weather and battery come from bin/weather and bin/battery; battery goes red when low.

The window name tracks repo:branch automatically via a zsh precmd hook.

Defined in config/nvim/init.lua. Leader is , (both mapleader and maplocalleader).

Press , and pause — which-key pops up the available continuations, grouped as g git, h hunks, x diagnostics, c code, t toggle.

Bound on LspAttach, so they exist only in buffers with a language server.

Servers auto-install via Mason: pyright, ts_ls, kotlin_language_server, lua_ls, and sourcekit (Swift, via Xcode). Format-on-save runs through conform.nvim (ruff / prettier / stylua / swiftformat / ktlint); linting is async via nvim-lint.

Defined in zshrc — zsh + oh-my-zsh + Spaceship prompt.

md is deliberately not markdown — it stays oh-my-zsh's mkdir -p. auto_cd is on, so a bare directory name cds into it, and cdpath covers ~, ~/Projects, and ~/Projects/src/github.com.

Defined in gitconfig. Use as git <alias> (or g <alias>).

Because pull.rebase, push.autoSetupRemote, rebase.autosquash, and fetch.prune are all on, git pull never makes a merge commit and first-push never needs -u origin.

Ghostty and yazi otherwise run on their default keymaps — neither config overrides any bindings.

Adding a binding? Add it to the owning file and to the matching table here.