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.

8 min read • View on GitHub • More from mizchi

A wide command-center scene shows a human developer at one side of a white desk and a mechanical AI hand at the other. Between them sit modular skill cards, a terminal window, and labeled cabinets for config, skills, and dependencies, showing that the workstation is built for both human and agent workflows.
This repo treats the workstation as shared territory. The point is not a prettier shell, but an environment where Claude Code can operate with the same structure a human would expect.

macOS dotfiles managed with chezmoi.

mizchi, Author/Maintainer · mizchi/chezmoi-dotfiles - GitHub
Key Takeaways

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.

A hedcut-style portrait of mizchi based on the public GitHub avatar. The image identifies the maintainer behind the repo and gives a face to the system designer described in the article.

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.

A close-up workbench shows a loop of papers, tools, and gates. An instruction sheet enters a static analysis checkpoint, passes into a task execution station, then drops into a retrospective notebook before flowing back into a rule shelf and skill archive. The image explains how the repo learns from completed work.
The repo does not stop at reusable setup. It tries to convert completed work into better instructions, better checks, and better skills for the next run.

Why the repo feels different from normal dotfiles

The architecture is layered, but the important part is the loop. Instructions shape behavior, behavior produces lessons, and lessons become the next instructions.

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.

ApproachStrengthWeaknessAgent readiness
Manual scriptsFast to startDrifts quickly and becomes brittleLow
GNU StowClean symlink managementLittle help for templating or AI workflowsMedium
mizchi/chezmoi-dotfilesTemplate-driven, skill-based, self-updatingMore complex to design and maintainHigh

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.

LayerTraditional dotfilesThis repo
InstructionsManual notes or commentsTemplated agent instructions in `CLAUDE.md.tmpl`
CapabilitiesAd hoc scriptsVersioned skills under `dot_claude/skills/`
DependenciesShell packages and pluginsAPM-managed AI capability sources
Quality controlHuman reviewStatic 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.

mizchi, Author/Maintainer · mizchi/chezmoi-dotfiles - GitHub

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.