A dotfiles repo maintained by an LLM. You operate your Mac freely; Claude detects what drifted and syncs it back to the repo on your approval. You never manually keep this repo in sync.
Most dotfiles repos expect you to edit the source, apply, commit, push. In practice, nobody does this consistently. You brew install while debugging, tweak a config directly, add an API key, and move on. After a few weeks, the repo is stale.
This repo works differently. You change things on your machine. Periodically, you ask Claude to catch up:
You: /dotfiles-sync
Claude: [scans machine - packages, configs, extensions, secrets]
Claude: Dotfiles sync report
Config drift: Zed settings (2 new MCP servers)
New packages: ollama, rclone, pandoc
Stale: raycast, slack (not installed)
VS Code: 5 new extensions
What should I do?
You: sync everything, drop raycast and slack
Claude: [edits Brewfile, re-adds configs, updates extensions,
logs to sync-log.md, commits]
Done. Push?
You: push
Two sentences from you. The LLM handled 6 file edits, a commit message, and a push.
The pattern is general and works with any dotfiles manager and any LLM agent. The full write-up, including setup instructions, is in docs/llm-dotfiles.md.
chezmoi is the backbone. It separates the source (repo) from the target ($HOME), renders templates with injected secrets, and provides drift detection via chezmoi status. This two-layer model is what makes LLM-maintained sync possible: the LLM can safely scan, diff, and re-add without touching secrets in git.
The /dotfiles-sync command is installed to ~/.claude/commands/ during setup, so it's available in Claude Code from any directory. The command prompt (at .claude/commands/dotfiles-sync.md) teaches Claude what to scan:
| Dimension | What it detects |
|---|---|
| Config drift | Files changed on machine but not in repo |
| Brew packages | Installed but not in Brewfile (and vice versa) |
| Cask apps | GUI apps installed but not tracked |
| VS Code extensions | New or removed extensions |
| Fish functions | Functions created outside chezmoi |
| SSH configs | New host configs in config.d/ |
| Secrets | Hardcoded keys that should be in 1Password |
Every sync is logged in docs/sync-log.md so future syncs have context.
git clone https://github.com/dwarvesf/dotfiles ~/dotfiles
cd ~/dotfiles && ./install.shA gum-powered wizard prompts for your name, email, editor, headless mode, and 1Password. First run takes ~30 minutes (Homebrew downloads). After that, just use /dotfiles-sync to keep things current.
Requirements: macOS 12+, Apple Silicon (Intel works too).
Other install methods
Existing Mac (configs only, skip brew/mas/defaults):
cd ~/dotfiles && ./install.sh --config-onlyWithout git (fresh Mac, no Xcode CLT):
sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply dwarvesfFlags: --check (dry-run), --force (reinit from scratch)
| Layer | Tools |
|---|---|
| Shell | Fish + Starship prompt + plugins (autopair, done, sponge, async-prompt) |
| Terminal | Ghostty (GPU-rendered, catppuccin-mocha, JetBrains Mono) |
| Multiplexer | tmux (C-a prefix, vim nav, fzf session picker) |
| Editors | VS Code + Zed (settings, extensions, MCP servers with 1P secrets) |
| Git | delta diffs, aliases, commit template |
| SSH | 1Password SSH Agent, modular config.d/ |
| Secrets | 1Password op:// templates + data-driven registry |
| Packages | Layered Brewfile (base/dev/apps) + Mac App Store |
| Languages | mise (Node, Python, Go, Ruby) |
| macOS | 30+ defaults write (Dock, Finder, keyboard, screenshots) |
Every tool is chosen for speed, ergonomics, and native macOS integration. No legacy defaults, no bloat.
When you're not in a Claude session (SSH, airplane, quick edit), the dotfiles CLI works standalone:
dotfiles edit ~/.config/fish/config.fish # edit + apply + auto-commit
dotfiles drift # detect and re-absorb drift
dotfiles doctor # health checkFull command reference, walkthroughs, secrets management, multi-machine setup, and troubleshooting are in the user guide.
| Stage | Command |
|---|---|
| Install | git clone ... ~/dotfiles && cd ~/dotfiles && ./install.sh |
| Update (LLM) | /dotfiles-sync in Claude Code |
| Update (manual) | dotfiles update (pull + apply) |
| Reinstall | ./install.sh --force |
| Uninstall | See guide |
This repo is safe to make public. Actual secrets (API keys, tokens, passwords) are never committed; only op:// references to 1Password items appear in the source. Real values are resolved at chezmoi apply time and only exist on your machine.
The op:// references do reveal 1Password vault and item names (e.g. op://Private/OpenAI/credential). This is intentional: it makes the repo forkable. If you fork, replace the item names with your own. The vault structure tells someone what services you use, not how to access them.
| Document | What it covers |
|---|---|
| docs/llm-dotfiles.md | The LLM-maintained dotfiles pattern. Shareable, stack-agnostic. Includes setup instructions. |
| docs/guide.md | Full user guide. chezmoi details, manual commands, customization, secrets, multi-machine, troubleshooting. |
| docs/decisions/ | Architecture decision records (why chezmoi, Fish, Ghostty, 1Password, auto-commit). |
| docs/sync-log.md | Sync history. Append-only log of every Claude-assisted sync. |
Built with chezmoi. Inspired by halostatue/dotfiles and narze/dotfiles.
MIT