Single source of truth for AI agents (Claude, Codex, Copilot, and more)

A year ago "the team uses an AI assistant" was a single decision. Today it isn't. On the last repo I worked on, one developer drove Claude Code, another lived in Codex, and another used Gemini (it's free for students). Nobody was wrong. People reach for the agent they already pay for and already trust.

The trouble is that each of those tools reads its own instruction file, and we were maintaining all of them by hand. I just hate source duplication and that's exactly why I decided to create my own solution for that. Some cli tool that will automatically generate the instruction files for all agents from a single source of truth.

However, of course, I didn't check the internet first. It turns out that rulesync already exists and does exactly that. I was so happy to find it, I wanted to share it with you.

The lifehack

If your team uses more than one AI agent, write the instructions once and generate the rest. That's the whole trick.

Every agent reads its own file from its own path:

Same project, same conventions, five files to keep in lockstep by hand. Edit the dependency rules in CLAUDE.md, forget the rest, and the agents drift: Claude refuses a forbidden import, Copilot happily writes it, and review fills up with "the AI told me to" diffs. It's duplicated, hand-synced state - exactly what you'd never tolerate in code.

rulesync: one source, many outputs

rulesync treats agent instructions like a build artifact. You write the rules once under .rulesync/, declare which tools you target, and it generates every per-tool file for you.

.rulesync/
  rules/
    overview.md
    conventions.md
    clean-architecture.md
  subagents/
    contract-reviewer.md
    security-reviewer.md
    qa-engineer.md
  commands/
    verify.md
    scaffold-route.md
  mcp.json

One command fans that out:

1pnpm sync:agents   # rulesync generate
2

And you get the generated, git-tracked files each tool actually reads:

AGENTS.md                         # shared brief (Codex too)
CLAUDE.md                         # Claude Code
.github/copilot-instructions.md   # Copilot
.codex/config.toml                # Codex MCP + features
.claude/
  agents/        # subagents -> Claude
  commands/      # slash commands
.github/
  agents/        # subagents -> Copilot
  prompts/       # commands -> Copilot

Note the same security-reviewer subagent lands in both .claude/agents/ and .github/agents/, in each tool's own format. You wrote it once.

It's not just rules

The part that sold me is that rulesync syncs the whole agent surface, not just the prose:

• Rules - your conventions as plain markdown with a tiny frontmatter block. A targets field decides which agents get a rule ("*" for all, or "claudecode" for one), and globs can scope it to certain files.
• Subagents - a security-reviewer or qa-engineer defined once, emitted for every tool that supports subagents.
• Slash commands - verify, scaffold-route, pre-pr become Claude commands and Copilot prompts from the same source.
• MCP servers - declare a dev server once in mcp.json; it's written into Claude's config and Codex's config.toml.

The config that maps sources to targets is small and well documented - I won't repeat it here, the README covers every field. The one habit worth stealing: keep AGENTS.md rules-only so it stays a clean brief a human can actually read.

Why it pays off, even with two people

For a solo repo with one agent, skip all of this and just write the file. The value scales with how many agents your team runs, and the threshold is low - it kicks in at two.

• One edit, one review, one diff. Change a convention once; every agent updates in the same commit. No "did you also update Copilot's file?" in review.
• No silent drift. Two engineers can't unknowingly run on different rules, so the AI stops contradicting itself across people.
• Onboarding a new tool is trivial. Teammate brings their favorite agent? Add a target, regenerate, done - they inherit the same rules, subagents, and commands as everyone else.
• Everything travels together. Conventions, subagents, slash commands, and MCP servers ship as one set, not four half-synced copies.

It scales past your own repo

If you ship a starter template or scaffold consumer projects from a base repo, this gets even better. Because the agent setup is generated from a single source, every project that clones the template starts with the same Claude / Codex / Copilot configuration baked in - same conventions, same reviewers, same commands. A team that consumes your platform doesn't hand-write any of it; they run generate and get a consistent agent experience on day one. The rules become part of the product, not tribal knowledge.

Make drift impossible

Generated files are committed, so the real risk is someone editing a generated file by hand and losing it on the next run. Close that gap in CI:

// package.json
{
  "scripts": {
    "sync:agents": "rulesync generate",
    "sync:agents:check": "rulesync generate --check"
  }
}

--check fails if the committed output doesn't match what the source would produce. Wire it into your pipeline and a stale CLAUDE.md becomes a red build, not a silent divergence. A prepare hook that runs generate on install keeps fresh clones honest too.

Wrap up

The mental model is simple: your agent config is code, so generate it, don't copy-paste it. Pick your sources once, let rulesync emit the rest, and gate it in CI. After that, "which file do I edit?" stops being a question - and your agents stop disagreeing with each other in code review, no matter who on the team is driving which one.