Chezmoi! Chez-what?!

Chezmoi! It's a word I can't get enough of. But what is it?

What does chezmoi do?

Chezmoi (pronounced "shay-mwa", it's French for "at my place") helps you manage your personal configuration files: dotfiles, like ~/.gitconfig, ~/.zshrc, ~/.claude/, across multiple machines. It keeps a canonical copy of every config file in a git repository. If the live file on your machine drifts from that copy, you see it instantly. One command to check. One command to fix.

Simple concept. Been around for years. Mostly used by Linux nerds who want the same shell config on every machine.

So why am I writing a newsletter about it?

Why is that useful?

Because chezmoi solved two core problems I've been struggling with for a long time.

Problem 1: I couldn't see my AI

Here's what I mean. I had limited (honestly, almost no) visibility into the current state of my AI's behavior. The only way I could tell if something changed was by using it and vibing. Literally vibing its vibes.

But Claude's behavior isn't magic. It's managed by configurations. MCP server definitions. CLAUDE.md files: the instructions that shape how Claude approaches every task. Skills. Hooks. Settings. Systems layered on top of systems. All of these different behaviors that Claude has are configurable. Every one of them lives in a file somewhere on your machine.

If you're like me, you're using Claude to make workflows for Claude. To install tools, understand how to connect services, manage your computer, not just as a coding tool. I've been using Claude to change its own configuration options. To write and rewrite its own CLAUDE.md. Even the /init command writes Claude's MD file. Claude is configuring Claude.

Problem 2: What changed?

This is where it gets painful.

We know what Claude feels like. You develop an intuition for your setup. You know when it's sharp and when it's off. And there are times where I've used Claude one week and the next week it feels terrible. The responses are different. The workflows break. Something shifted.

I don't like putting that down to just Anthropic changing something on their end. I put it down to something changed about my configuration, and I don't know what.

I needed the answer to one question: what changed?

Git was the obvious answer.

But why doesn't git work here?

Here's the thing: you can't just git init inside ~/.claude/ and call it done.

These config files are scattered across your filesystem. ~/.claude/ for Claude's core config. ~/.config/ for MCP server definitions and tool configs. ~/.local/bin/ for launcher scripts. ~/.zshrc for shell environment. Some files are in your home directory root. Some are nested three levels deep in application-specific folders.

Git tracks a directory. These files don't live in one directory. They live everywhere.

You could try symlinking everything into a single repo, but that's fragile. Permissions get wrong. Applications break when they detect symlinks instead of real files. Some files need to be private (mode 700), like your entire .claude/ directory, and git doesn't track Unix permissions properly.

And the real killer: some of these files contain secrets. API keys that shouldn't be in a git repo, even a private one. You need templating: a way to say "this file has a secret here, pull it from my password manager at apply time."

Git alone can't do any of this. Chezmoi can.

How chezmoi solves this

Chezmoi manages files across your entire filesystem from a single git repository. It doesn't care where the files live: home directory, .config, .local/bin, anywhere. You add a file with chezmoi add, and it copies it into its source directory with a naming convention that encodes the target path, permissions, and privacy.

private_dot_claude means: this maps to ~/.claude/, and it should be mode 700. dot_config/ means ~/.config/. The naming is the configuration.

Here's the workflow that changed everything for me:

chezmoi diff: shows you exactly what's different between your tracked source-of-truth and what's actually on your machine right now. One command. Every file. Every change. This is the answer to "what changed?"

chezmoi apply: takes the source-of-truth and applies it to your live system. Broke something? chezmoi apply and you're back to known-good state in seconds.

chezmoi git log: because the source lives in git, you have a complete history of every change to every config file. With timestamps. With commit messages. You can see exactly when your AI started behaving differently and trace it to the specific edit that caused it.

What I've caught with chezmoi

This isn't theoretical. Here's what it's surfaced for me in three months of daily use.

THE SECURITY INCIDENT THAT DIDN'T HAPPEN. An API key silently crept back into my settings after Claude tried to fix an unrelated config issue. chezmoi diff surfaced it before I pushed anything. The key never left my machine.

THE FIVE-FILE SILENT BREAKAGE. A plugin rename broke hooks across five separate files. No errors, no warnings: just things quietly not working. Chezmoi showed me every broken reference in one diff. What would have been days of confused debugging took seconds.

THE INVISIBLE TAX. Thirteen dead MCP server configurations accumulated over weeks. Config rot that degrades performance without any single moment you'd notice. One tracked cleanup, reproducible on every machine.

THE WEEK CLAUDE FELT WRONG. I could pinpoint exactly when a skill iteration made Claude worse: not a feeling, a diff. A timestamp. A commit I could roll back to. And I did, and it was immediately better.

THE PLAYWRIGHT PERSISTENCE FIX. We use Playwright for browser automation: screenshots, form filling, visual verification. It was launching a fresh browser every session. No cookies, no login state. Every session meant re-authenticating to Google, LinkedIn, everything. 2FA kept blocking us. The fix? One JSON config file telling Playwright to use a persistent profile directory. That config file is managed by chezmoi. Tracked, versioned, reproducible on any machine.

This is the pattern: something breaks or wastes time. The fix turns out to be a config change. Chezmoi makes that fix permanent and portable.

The portability bonus

There's a side effect I didn't anticipate: my entire AI stack (skills, hooks, MCP servers, settings, launch scripts) lives in chezmoi's git repository. One command on a new machine and the environment is identical. Same behavior, same capabilities, same guardrails.

If you've ever rebuilt a development environment and spent hours getting your AI tools configured the way you like them, you know why this matters.

What we built on top of it

At Atlas AI we went further than basic tracking. We built a skill that runs inside Claude Code and detects config drift automatically.

Here's why that matters. Not all drift is equal. Usage counters increment every session, that's just ephemeral noise. But if a hook definition changed, or an MCP server config got modified, or a skill file was rewritten, that's meaningful.

The system catches meaningful drift and asks a simple question. Did the source fall behind, or did the live file go rogue?

Sometimes the live file has a legitimate improvement that should go back into the source. Sometimes Claude made a confident edit that broke something and should be reverted. The system surfaces the question instead of letting the drift pile up silently.

The skill runs at session start. It checks chezmoi diff, classifies what changed, and asks what you want to do before you start working. No more discovering three hours in that something fundamental is broken.

More details on the package soon.

Where this is going

Here's the part I've been thinking about, and it's the reason this is a series instead of a single post.

If you're tracking every change to your AI's behavior in git, every skill iteration, every config tweak, every settings change, you have structured data about what makes your AI effective. You know what was running when Claude felt sharp. You know what changed when it didn't.

Now imagine feeding that history into a vector database. Every commit becomes a searchable document. Every diff becomes context. You can ask "when was the last time I had this problem?" and get back the exact commit that fixed it. You can ask "what was my config when summarization worked well?" and get a snapshot.

Take it further. Use an LLM as a judge. Have it evaluate your AI's outputs against the config state that produced them. Build a RAG system that doesn't just retrieve documents but retrieves your own AI's behavioral history. The debugging sessions you've already solved. The configurations that produce good results. The patterns that are unique to your Claude, not anyone else's.

And if you can structure that data cleanly enough, chezmoi gives you that structure for free, you could potentially fine-tune local models on it. Train an AI that already knows your preferences and patterns. Not a generic model. Yours.

Subscribe for the next deep dive. How RAG from config history actually works.

---

- Hayden Bruinsma, Atlas AI
atlas-ai.au