When you let an AI agent share your machine for a year, you eventually hit a question you can't answer: why does my setup look like this?
Not "what does it look like" — that's just cat. The why. Which config landed when, which edit was the agent's own work versus mine, which assumption got baked in three commits ago and is now invisible. If you've used Claude Code long enough to have an evolved settings file, a memory store, and a handful of skills installed, you already recognize the feeling.
I've been versioning Claude Code's configuration files since July 2025. Memory joined the repository in April 2026. The setup is mundane — a private git repo and a handful of symlinks — but the effects compound, and most of them I didn't anticipate when I started.
A small but important clarification
Claude Code doesn't edit its own configs autonomously. It only edits them when you ask it to, or when you've set up a workflow that includes "persist this to settings." That distinction matters for everything below: the audit trail is valuable not because the agent goes rogue, but because the agent does what you asked — and a week later, you no longer remember exactly what you asked for.
It also matters because Claude Code's settings live at different scopes. The global ~/.claude/settings.json is the one I've seen the agent touch most. User-scoped and project-scoped overrides have been more cautious in my experience. Memory is its own thing again, scoped per project working directory.
The mechanism
Claude Code writes its state to predictable paths:
- Global settings:
~/.claude/settings.json - Project-scoped memory:
~/.claude/projects/<encoded-cwd>/memory/ - Skills, hooks, MCP configs: various
~/.claude/...subfolders
<encoded-cwd> is deterministic — your working directory with slashes replaced by dashes. That predictability is the entire leverage point. If the path is constant, you can symlink it into a git repo and the agent doesn't know the difference.
The setup
# 1. Move the target dir into your private configs repo
mv ~/.claude/projects/<encoded-cwd>/memory \
~/configs/claude-code/projects/<encoded-cwd>/memory
# 2. Symlink back so Claude keeps reading at the original path
ln -s ~/configs/claude-code/projects/<encoded-cwd>/memory \
~/.claude/projects/<encoded-cwd>/memory
# 3. Commit
cd ~/configs && git add . && git commit -m "claude-code: memory under version control"
That's it. Claude continues reading and writing at the same path. Git tracks every change. Repeat for any other ~/.claude/... subtree you want to capture.
After symlinking, the configs repo holds the canonical state. The diff is what you actually review.
What changed
I started narrow — I wanted a backup of settings.json in case something blew it away. The effects below emerged as the repo grew. None of them were the original motivation.
Audit trail
git log on the configs directory tells me what was rewritten when. git diff on a settings file shows me what changed yesterday. When the agent edits a settings file on my behalf — which happens whenever I run a setup or skill that persists state — the diff is the only honest record of what actually landed. Six months in, this is the effect I use most.
Every memory update, every correction, every policy tightening becomes one line in the log.
Rollback for bad generalizations
Sometimes a memory entry lands wrong. A correction the agent generalized too broadly, an entry that survived past its expiration. git checkout HEAD~N -- claude-code/projects/.../memory/<file>.md and the entry is gone, exactly as it was three days ago. Without version control, that path is one-way.
Backup resilience
~/.claude/ is an application home directory. A stray cleanup, a beta update that resets state, a disk failure — any of these can erase months of accumulated context. With the repo as the source of truth and symlinks pointing back, the recovery is git clone plus re-linking. That's it. If you're more paranoid, you can also push the repo to a private remote and have an offsite copy.
The fix-buddy effect
This is the one I didn't see coming. Once the repo contains the full agent setup — settings, skills, memory, MCP configurations — the agent itself can read its own history through git. When something breaks, I don't need to explain to Claude what its setup looked like a week ago. It can look. That changes what "debugging your AI workflow" feels like, because the agent is no longer guessing at its own past.
A note for multi-machine setups
If you do run Claude Code on more than one machine, a private remote plus git pull before each session gives you the same context everywhere. I run on one machine, so I haven't pressure-tested this; the moving parts (system-level paths, OS-specific binaries) make me cautious to promise it as a turnkey thing. But the file-level setup is there if you want to try.
The re-framing
The hack isn't the symlink. The hack is the relabeling.
Most people treat ~/.claude/ as application state. Browsers, IDEs, package managers all have similar directories, and the default reflex is to leave them alone — they're cache, they're ephemeral, they regenerate. That reflex is correct for browser cache. It's wrong for agent configuration.
Agent configuration is closer to code than to cache. It encodes intent: which model to use, which skills to load, which corrections to apply, which mistakes to avoid. That's documented behavior. Once you see it that way, every standard versioning argument applies — history, diff, rollback, sharing, review. The symlink trick is just the mechanical step that lets you act on the new framing.
A note on privacy
The repo is private. What exactly counts as sensitive is your call, not a checklist someone else writes.
What I'd tell someone starting today
Don't begin with memory. Begin with settings.json. Symlink it, commit it, watch it for a week. The diff will surprise you — settings drift more than you'd think, and seeing the drift is the first win.
Expand from there as you build trust in the pattern. Memory is a natural extension once the rest of the agent's state is already under git.
Ephemeral state is a design choice, not a fact of nature.
Top comments (0)