{"slug": "manage-your-claude-code-config-with-dotfiles-and-gnu-stow", "title": "Manage Your Claude Code Config with Dotfiles and GNU Stow", "summary": "Developer Yuri Koval recommends managing Claude Code configuration with a dotfiles repository and GNU Stow, enabling version control rollbacks and easy machine migration. The approach tracks skills, hooks, plugins, and MCP server definitions in a git repo, allowing users to revert broken changes with git revert and clone setups on new machines with one command. Koval warns against committing API keys and suggests using secret management tools like Keychain, 1Password CLI, and direnv.", "body_md": "Track your coding agent’s config in a dotfiles repo. I did this using git with [GNU Stow](https://www.gnu.org/software/stow/), and it helps me in two ways: I can **roll back a skill** that broke after one edit too many, and I can **clone my setup** on a new dev machine with one command.\n\nHere’s how you can do the same.\n\n“Claude Code config” used to mean a settings file and maybe a `CLAUDE.md`\n\n. Mine now holds skills, hooks, plugins, slash commands, subagents, workflows, and MCP server definitions. I’m probably forgetting a few. Dozens of files with a new one added every time a new capability is shipped.\n\nModels and coding agents change fast, and naturally your workflow changes with them. Every release means another round of tweaked prompts and updated skills. At some point this stopped being configuration and became a small codebase. Almost all of it is plain text and JSON in one directory, which makes it a perfect candidate to manage with source control.\n\nOne edit too many and you wish you had a way to roll back the changes you made. Imagine you have your own version of the [Lyra prompt](https://yurikoval.com/blog/lyra-prompt.html), and you make incremental changes, but decide to roll back a few versions – having this setup would save you from losing your work up until that point.\n\nYou find a skill someone shared, customize it, and keep tuning it for weeks. One day it starts failing and you can’t remember what it looked like back when it worked. It gets worse when you let AI draft or update the skill itself (Claude editing Claude’s config) and the new version is suddenly broken.\n\nWithout version control, you lose your work with the latest update, but with git it’s `git diff`\n\nto see what changed and `git revert`\n\nto get back to the version that worked. This has saved me more than once.\n\nEasier machine migration is what made dotfiles popular in the first place, and it counts double now. Your shell aliases and editor config already travel this way. Add `~/.claude`\n\nto the repo and your whole AI setup lands on a fresh machine with a single script, instead of you re-teaching Claude Code your workflow from scratch.\n\nDotfiles are the hidden config files in your home directory: `.zshrc`\n\n, `.gitconfig`\n\n, and now `.claude/`\n\n. A dotfiles repo is a small git project that holds all of them, plus a script to link or copy them into place. Your machine’s personality, versioned. If you want to see how mine is structured, you can see it on GitHub ([yurikoval/dotfiles](https://github.com/yurikoval/dotfiles)).\n\nThere are [many ways](https://news.ycombinator.com/item?id=11070797) to do this, and any of them beats nothing.\n\nThe simplest is `git init`\n\ninside `~/.claude`\n\nand committing as you go, but you’re only tracking Claude’s configs. [Atlassian recommends](https://www.atlassian.com/git/tutorials/dotfiles) a bare repository with your home directory as the work tree, which skips symlinks entirely. If you’d rather have tooling, [yadm](https://yadm.io/docs/install) is a dotfiles manager that wraps git with per-machine alternates and encryption built in.\n\nI stuck with [GNU Stow](https://www.jakewiesler.com/blog/managing-dotfiles). Stow symlinks packages from your dotfiles repo into your home directory: `stow claude`\n\nlinks `~/.claude`\n\ninto place, and `stow -D claude`\n\nremoves it cleanly.\n\nThe tool matters less than the habit. Commit before you experiment, especially before you let AI rewrite its own config, and every failed iteration is one `git revert`\n\nfrom gone.\n\nOne warning before you push anything: dotfiles repos are exactly how API keys end up on GitHub. MCP server definitions and `.zshrc`\n\nexports love to collect them. Keep secrets out of the files you track – I wrote up [how I manage development secrets on a Mac](https://yurikoval.com/blog/managing-development-secrets-on-a-mac.html) with Keychain, the 1Password CLI, and direnv.", "url": "https://wpnews.pro/news/manage-your-claude-code-config-with-dotfiles-and-gnu-stow", "canonical_source": "https://www.yurikoval.com/blog/manage-ai-config-with-dotfiles.html", "published_at": "2026-07-02 02:00:00+00:00", "updated_at": "2026-07-07 14:04:04.204453+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "large-language-models"], "entities": ["Claude Code", "GNU Stow", "GitHub", "Atlassian", "yadm", "Keychain", "1Password", "direnv"], "alternates": {"html": "https://wpnews.pro/news/manage-your-claude-code-config-with-dotfiles-and-gnu-stow", "markdown": "https://wpnews.pro/news/manage-your-claude-code-config-with-dotfiles-and-gnu-stow.md", "text": "https://wpnews.pro/news/manage-your-claude-code-config-with-dotfiles-and-gnu-stow.txt", "jsonld": "https://wpnews.pro/news/manage-your-claude-code-config-with-dotfiles-and-gnu-stow.jsonld"}}