mizchi/chezmoi-dotfiles: The Dotfiles Repo Built for an AI Pair Programmer
A macOS setup where Claude Code, skill modules, and static analysis turn a personal environment into an agent-ready workstation.
macOS dotfiles managed with chezmoi.
- This repo turns dotfiles into an operating environment for Claude Code, not just a personal shell setup.
- Its real abstraction is the skill, which packages instructions into repeatable workflows the agent can actually execute.
- Static analysis and templated rules matter more here than prompt finesse, because the system prefers deterministic constraints over vibes.
- Retrospectives feed lessons back into the instructions, so the environment gets more disciplined after each task.
Most dotfiles repos optimize for one person at one keyboard. mizchi/chezmoi-dotfiles optimizes for a person and an agent sharing the same machine. That is the shift that makes it interesting.
The setup is macOS-centric and built with chezmoi, but the novelty is not the toolchain. It is the assumption that Claude Code is a first-class operator, expected to read instructions, call skills, and work inside the repo like a collaborator instead of a guest.
The workstation is now a collaborator
The repo is organized around the idea that the machine is no longer just responding to commands. It is participating in a workflow that includes setup, execution, verification, and review. That is why the Claude-specific layer matters as much as the shell layer.
Traditional dotfiles tune the human experience: aliases, prompt themes, editor settings, path fixes. Here, the configuration also teaches an agent how to behave. That changes the unit of design from convenience to coordination.
Why the repo feels different from normal dotfiles
The repo is split into familiar folders, but they are arranged with a new purpose. `dot_claude` holds the agent-facing layer, `dot_apm` manages external AI capabilities, `dot_config` contains standard tool settings, and `dot_zsh` still handles shell concerns.
That structure matters because it keeps the agent environment modular. Instead of one giant prompt blob, the repo can separate local instructions, reusable skills, and enforced checks.
| Approach | Strength | Weakness | Agent readiness |
|---|---|---|---|
| Manual scripts | Fast to start | Drifts quickly and becomes brittle | Low |
| GNU Stow | Clean symlink management | Little help for templating or AI workflows | Medium |
| mizchi/chezmoi-dotfiles | Template-driven, skill-based, self-updating | More complex to design and maintain | High |
Skills are the real interface
The most important abstraction in the repo is not a shell alias or a config file. It is the skill. Inside `dot_claude/skills/`, the author packages narrow procedures, decision trees, and runbooks that Claude Code can load as working context.
That makes skills more than documentation. They are executable intent. A skill can teach the agent how to handle `chezmoi-management`, or how to navigate a `cloudflare-deploy` decision tree without turning every task into a fresh prompt.
dot_claude/
skills/
chezmoi-management/
SKILL.md
cloudflare-deploy/
SKILL.md
ast-grep-practice/
SKILL.md
This is where the repository stops looking like a personal preference dump and starts looking like a control system. The human writes the policy once, then the agent executes against that policy many times.
Static analysis beats vague prompting
The technical center of gravity is `CLAUDE.md.tmpl`. It does not just give the agent a tone or a goal. It pushes the agent toward deterministic rules, especially `ast-grep`, so style and structure can be checked mechanically.
That choice is the opposite of prompt theater. Instead of hoping the model remembers a guideline, the repo encodes constraints that can be validated. In practice, that means fewer arguments about phrasing and more focus on whether the code actually matches the rule.
# Conceptual flow
Template instructions -> skill selection -> ast-grep validation -> task execution -> retrospective update
The payoff is simple. If the agent is going to operate inside your workspace, then the workspace should enforce its own standards.
APM turns AI instructions into dependencies
`dot_apm/apm.yml` treats agent capability like a package graph. That is a smart move because it makes prompts and skills portable, versionable, and easier to reason about than one-off instructions scattered across files.
It also changes how you think about sharing. In a normal dependency manager, you share libraries. In this setup, you share structured behavior: the procedures, constraints, and task-specific knowledge an agent needs to do useful work.
| Layer | Traditional dotfiles | This repo |
|---|---|---|
| Instructions | Manual notes or comments | Templated agent instructions in `CLAUDE.md.tmpl` |
| Capabilities | Ad hoc scripts | Versioned skills under `dot_claude/skills/` |
| Dependencies | Shell packages and plugins | APM-managed AI capability sources |
| Quality control | Human review | Static rules plus retrospective updates |
The repo improves itself after each task
The most elegant loop lives in `retrospective.md`. After work is done, the agent is asked to extract lessons, then feed them back into rules, instructions, or skills. That makes the setup more than a toolkit. It becomes a learning environment.
This is the piece that turns the repo from static infrastructure into living infrastructure. The machine is not only helping complete the task. It is helping rewrite the operating assumptions for the next one.
Uses prek with secretlint to prevent committing secrets.
What this says about the next generation of dotfiles
The comparison is no longer just between tools. It is between mental models. Hand-rolled dotfiles assume a human user. GNU Stow assumes a human maintainer. This repo assumes a shared environment where an AI agent is allowed to act, but only inside carefully defined boundaries.
That is a real category shift. Dotfiles stop being a pile of preferences and become operational policy for a workstation that serves both a developer and an agent.





