If you use Claude Code and Cursor, or you work across more than a handful of repos, you have met config drift: the CLAUDE.md in one project says one thing, the .cursor/rules in another says something else, and the AGENTS.md you wrote for Codex is three months behind both. Every agent gets a slightly different briefing, so every agent behaves slightly differently, and nobody can say which copy is the truth.
This post covers the five practical approaches to keeping agent configuration in sync, from zero-dependency symlinks to purpose-built tools.
Disclosure: I work on Blume, which appears as one of the five options. The other four are covered on their merits, and for many setups one of them is all you need.
The problem in one sentence
Every agent invented its own config location: Claude Code reads CLAUDE.md and .claude/ (rules, skills, hooks, settings), Cursor reads .cursor/rules/*.mdc, Codex reads AGENTS.md, and Copilot, Gemini CLI, and the rest have their own variants. The knowledge is 90 percent identical, but it lives in N places times M repos.
Option 1: Symlinks (the zero-dependency fix)
Make one file the source of truth and link the rest to it:
# AGENTS.md is the master; CLAUDE.md points at it
ln -sf AGENTS.md CLAUDE.md
A popular variant centralizes everything in one .agents/ (or .ai/) folder in the repo and symlinks each tool's expected path into it. Update the master file and every tool sees the change instantly.
Good for: single repo, cross-tool consistency.
Limits: does nothing across repos, and symlink behavior on Windows can be a headache for mixed teams.
Option 2: Hard links
Same idea, but the same physical file exists at multiple paths. Some prefer this because every path looks like a real file to tools that resolve symlinks oddly.
Good for: the same cases as symlinks, with slightly different edge cases.
Limits: hard links silently break when a tool replaces a file instead of editing it in place, which is exactly what some formatters and generators do. Drift returns without warning, which is worse than obvious drift.
Option 3: ai-rules-sync (cross-tool, git-backed)
ai-rules-sync manages rules, skills, commands, and subagents in a git repository and syncs them into projects via symlinks. It explicitly supports Cursor, Claude Code, Copilot, OpenCode, Trae, Codex, Gemini CLI, and Warp, which makes it the broadest cross-tool option.
Good for: individuals and teams who want one git repo as the canonical rule set across many projects and many tools.
Limits: you are adopting a tool and its conventions; the sync is still file-copy-shaped, so what to sync and when stays a human decision.
Option 4: RuleSync (CI-friendly distribution)
RuleSync distributes CLAUDE.md, .cursorrules, and settings files across repos with npx rulesync-cli pull, and it runs in CI. Adding it to postinstall means every checkout gets current rules automatically.
Good for: teams that want rule distribution to be part of the build, not a manual step.
Limits: pull-based distribution keeps files identical, but it cannot tell you whether the rules themselves are still correct.
Option 5: Blume (drift detection, not just distribution)
The four options above all solve copying: making sure the same bytes exist in the right places. Blume works on the layer above that. It is a desktop app that manages rules, skills, hooks, and the rest of your agent dotfiles centrally across Claude Code, Codex, and Cursor, and then does the part copying cannot: it watches how your agents actually behave, detects when setup and instructions have drifted apart (a rule one agent ignores, configs that contradict each other, a hook that never fires), and proposes fixes you approve or reject.
Sync tools keep copies identical. Identical copies of a rotten rule set are still rotten, and that second failure mode is the one that quietly degrades agents over months.
Good for: multi-agent setups where the config has grown beyond easy manual review.
Limits: it is a desktop app, so if you need headless CI distribution, pair it with option 3 or 4 rather than replacing them.
Which approach fits you
| Situation | Start with |
|---|---|
| One repo, two tools | Symlinks |
| Many repos, one person | ai-rules-sync |
| Team, rules must ship with checkout | RuleSync in postinstall |
| Multi-agent, config grown past manual review | Blume, plus symlinks in-repo |
These compose. A common stack is AGENTS.md as the in-repo master with symlinks, a git-backed rule repo for cross-project sharing, and something watching for drift on top.
FAQ
Which file should be the master?
AGENTS.md, because most agents now read it natively (Codex, Cursor, Copilot CLI, Gemini CLI, and Claude Code). Keep genuinely Claude-specific instructions in a small CLAUDE.md that defers to it.
Should agent config be committed?
Project-level rules, yes: they are institutional knowledge and belong in review. Personal preferences and secrets, no.
How do I know if my configs have already drifted?
Quick check: diff CLAUDE.md AGENTS.md in any repo where both exist as real files, and compare rule counts across your most-touched repos. If you find contradictions in five minutes of looking, there are more you did not find.
If you have a sync setup I did not cover, especially for larger teams, drop it in the comments.
Top comments (1)
Config drift between agent instruction files is a real production problem. I like treating these files less like notes and more like policy artifacts: owned, versioned, tested, and synced with a clear source of truth.