Personal macOS-first shell, terminal, editor, and developer-tool configuration managed with Chezmoi. Linux and HPC hosts receive a smaller compatible subset.
Start here. These guides assume a clean macOS installation without an iCloud backup. Keep the current Mac available until final verification passes.
Complete setup/01_prepare_current_mac.md on
the old Mac. This backs up secrets, stores the age identity, and confirms the
repository and personal data are available remotely.
On the new Mac, complete
setup/02_bootstrap_macos.md, then run the
Clone Without Applying section of
setup/03_install_dotfiles.md. Do not use
chezmoi init --apply.
For agent-guided setup, install and launch OpenCode from the cloned repository:
brew install anomalyco/tap/opencode
opencode "$HOME/.local/share/chezmoi"Complete provider authentication, then send:
Read setup/AGENT_SETUP_PROMPT.md and follow it exactly.
Keep this session interactive; do not use --auto. The
agent prompt pauses clearly for secrets,
passphrases, authentication, system permissions, external portals, and approval
before applying changes.
For manual setup, continue from Install Core Software in phase 3, then follow the remaining guides in order:
setup/03_install_dotfiles.mdsetup/04_restore_secrets_and_auth.mdsetup/05_restore_apps_and_data.mdsetup/06_verify_setup.md
Do not skip preview, secret rotation, or final verification steps.
- Bash aliases, functions, prompt, completion, history, and vi-style editing
- Minimal zsh fallback configuration
- Git, Git LFS, Delta, GitHub CLI defaults, and global ignore rules
- Neovim configuration and pinned plugin lockfile
- tmux, TPM, session persistence, and sesh integration
- Starship, WezTerm, Atuin, btop, neofetch, Television, and The Fuck
- Arc, Raycast, Slack, Tailscale, Obsidian, Teams, WhatsApp, Zoom, VLC, Thunderbird, and Steam
- Reproducible Dock ordering, small spacer groups, stack, and visual settings
- OpenCode agents, MCP servers, Cloudflare skills, Caveman, and Ponytail
- VS Code settings, keybindings, and reviewed extensions
- Safe Vorssaint preferences
- Encrypted SSH config; private SSH keys remain machine-local
- Encrypted iCloud transfer helper for machine-local secrets
- Python environment helpers and utility scripts
Machine-local credentials live in ~/.config/dotfiles/secrets.sh. This file is
never managed by Chezmoi or Git.
home/: Chezmoi source state mapped into the home directoryBrewfile: core software required by managed configurationBrewfile.optional: opt-in scientific, compiler, and specialist softwaresetup/: ordered new-Mac setup instructionsdocs/: audit records, migration notes, and application inventory
Fetch and preview before applying:
chezmoi git pull -- --ff-only
chezmoi status
chezmoi diff
chezmoi apply --dry-run --verbose
chezmoi applyUse chezmoi edit <target> to change managed files, or edit the directory
returned by chezmoi source-path. Never force-apply over unexplained local
changes.
Install Chezmoi with the platform package manager or official installer, then preview before applying:
sh -c "$(curl -fsLS get.chezmoi.io)"
chezmoi init https://github.com/WillJRoper/dotfiles.git
chezmoi diff
chezmoi applyHomebrew manifests and macOS application scripts are macOS-specific.
docs/MIGRATION_CHECKLIST.mddocs/APPLICATION_INVENTORY.md- Component documentation under
home/dot_config/