Agents Sync

agents-sync

Make your AGENTS.md actually read by Claude Code — and keep every other AI tool in sync automatically.

11 AI tools · auto-loaded in every session · zero-cost template mode · ~$0.03–0.06 per AI sync

[](https://www.npmjs.com/package/@googlarz/agents-sync) [](LICENSE) [](https://nodejs.org)

[](https://claude.ai/code) [](https://cursor.com) [](https://github.com/openai/codex) [](https://opencode.ai) [](https://kiro.dev) [](https://trae.ai)

---

The Problem

You migrated from Prisma to Drizzle three weeks ago. You updated CLAUDE.md. Last Thursday, your colleague opened the project in Cursor — .cursorrules still said "use Prisma ORM". They wrote a new migration using Prisma. The PR landed on Friday. You found it Monday morning.

You moved auth to a separate src/auth/ module two sprints ago. The directory restructure is in git. Every AI tool still thinks auth lives in src/lib/. New engineers onboard, get confidently wrong suggestions on day one, and blame themselves for not understanding the codebase.

You added a "never use any type" rule to CLAUDE.md in January. It's May. Copilot never heard about it. Windsurf never heard about it. The rule exists in one file, enforced by one tool, ignored by everything else.

Each of these happened because context files drift. Not dramatically — just one update here, one forgotten file there, until the gap between what you wrote and what your tools know is wide enough to cause real damage.

Every AI coding tool expects its own context file:

| Tool | File | |---|---| | Claude Code | CLAUDE.md | | Cursor | .cursorrules | | GitHub Copilot | .github/copilot-instructions.md | | Codex / opencode / Amp | AGENTS.md | | Gemini CLI | GEMINI.md | | Windsurf | .windsurfrules | | Cline | .clinerules | | Roo Code | .roomodes | | Aider | CONVENTIONS.md | | Kiro (Amazon) | .kiro/steering/agents-sync.md | | Trae (ByteDance) | .trae/rules/agents-sync.md |

Maintain them manually and they drift. agents-sync generates all of them from a single canonical AGENTS.md — derived from your actual codebase, updated whenever your stack changes.

This is GitHub issue #6235 — AGENTS.md portability, 3,914 upvotes, the most demanded feature in the Claude Code repo.

---

Why Not Just Write CLAUDE.md Once?

You can. If you only use Claude Code and your stack never changes.

It doesn't stay written once.

It goes stale silently. Add drizzle-orm, rename src/features/ to src/modules/, onboard a new dev who restructures things — your context file is now wrong. You won't notice until an AI confidently generates a Prisma migration two weeks after you switched to Drizzle.

You need nine files, not one. CLAUDE.md covers Claude Code. Your colleague uses Cursor. CI runs Copilot suggestions. New hires bring Windsurf or Cline. Each tool has its own format, its own instructions, and its own staleness clock. A manually-maintained CLAUDE.md leaves everyone else with nothing.

agents-sync closes the loop: scan actual code → Claude extracts architecture and conventions → canonical AGENTS.md → all eleven files derived automatically. Run once. Drift detected at every commit. Re-sync in seconds when it matters. The context files stop being something you remember to update and become something that's just always correct.

One more thing worth knowing: Claude Code silently drops CLAUDE.md rules after context compaction — your carefully-generated instructions vanish mid-session without warning. agents-sync can't fix that (it's a Claude Code bug), but cc-safe-setup's subagent-claudemd-inject hook re-injects critical rules into subagent prompts as a mitigation.

---

Quick Start

Already have AGENTS.md? One command makes Claude Code read it automatically — no init, no API key:

# This project only:
npx @googlarz/agents-sync load-context .

# Every project on this machine (run once, done forever):
npx @googlarz/agents-sync load-context --global

✓ Installed Claude Code SessionStart hook
  → /your/project/.claude/settings.json

AGENTS.md will now be auto-loaded as context at the start of every Claude Code session.
Works from subdirectories — walks up to git root to find all AGENTS.md files.

That's it. If you want to also generate AGENTS.md, keep all tools in sync, and detect drift — read on.

---

Starting from scratch? Step 1 — scan your project (no API key, no cost):

npx @googlarz/agents-sync scan .

agents-sync scan — my-app

▸ Project
  Language:    typescript
  Framework:   next.js
  Runtime:     node
  Pkg manager: npm

▸ Dependencies
  31 production, 22 dev
  Notable: next, react, drizzle-orm, @auth/core, zod, tailwindcss +25 more

▸ Structure
  Top-level dirs: src, public, drizzle
  Total files:    ~412
  Entry points:   src/app/page.tsx
  Test dirs:      src

▸ MCP Servers (.claude/settings.json)
  ✓ postgres — PostgreSQL database access
  ✓ github — GitHub API integration

▸ Local Skills & Commands
  ✓ /deploy — Production deployment checklist
  ✓ /db-migrate — Database migration workflow

▸ Gotchas found in source
  FIXME src/lib/auth.ts:42 — token refresh race condition, needs mutex
  HACK  src/db/client.ts:17 — direct pool access bypasses connection limit
  TODO  src/api/webhooks.ts:91 — validate Stripe signature before processing

Scanned in 287ms · ~21,400 tokens of context

→ Ready to init. Run:
  ANTHROPIC_API_KEY= npx @googlarz/agents-sync init .
  Get a key: https://console.anthropic.com/

Step 2 — generate all context files:

No API key? No problem — templates work without one:

npx @googlarz/agents-sync init .

With an API key for AI-powered output (~$0.03–0.06 per sync with the single-call pipeline):

ANTHROPIC_API_KEY=sk-ant-... npx @googlarz/agents-sync init .

✓ AGENTS.md → /your/project/AGENTS.md
✓ claude   → /your/project/CLAUDE.md
✓ cursor   → /your/project/.cursorrules
✓ copilot  → /your/project/.github/copilot-instructions.md
✓ gemini   → /your/project/GEMINI.md
✓ windsurf → /your/project/.windsurfrules
✓ cline    → /your/project/.clinerules
✓ roo      → /your/project/.roomodes
✓ aider    → /your/project/CONVENTIONS.md
✓ kiro     → /your/project/.kiro/steering/agents-sync.md
✓ trae     → /your/project/.trae/rules/agents-sync.md

✓ Snapshot saved to .agents-sync/

Add AGENTS.md to git. Add .agents-sync/ to .gitignore.

---

What Gets Generated

Sample AGENTS.md

# AGENTS.md

## Project Overview
my-app is a SaaS dashboard built with Next.js 15 App Router, PostgreSQL
via Drizzle ORM, and Auth.js v5 for authentication.

## Tech Stack
- TypeScript / Next.js 15 (App Router)
- PostgreSQL via Drizzle ORM
- Authentication: Auth.js v5
- Testing: Vitest (co-located)
- Deploy: Vercel

## Architecture
- `src/app/` — Next.js pages and layouts (App Router)
- `src/features/` — feature modules (billing, users, dashboard)
- `src/lib/` — shared utilities: db singleton, auth config, api client
- `src/components/` — shared UI components (shadcn/ui)

## Conventions
1. kebab-case filenames throughout
2. Named exports only — no default exports except Next.js page/layout components
3. All external input validated with Zod before use
4. Co-locate tests: `Button.test.tsx` next to `Button.tsx`
5. Server components by default; `"use client"` only when required

## Gotchas
1. Never import the db client directly — use `lib/db.ts` singleton.
   Direct imports cause connection pool exhaustion in serverless.
2. All API routes require auth middleware — check `middleware.ts` first.
3. `src/lib/auth.ts:42` has a known token refresh race condition.
   Workaround in place; do not remove the mutex.

## Boundaries

### Never
- Commit `.env` or `.env.local`
- Import `db` outside of `lib/db.ts`
- Use `any` type — use `unknown` and narrow
- Bypass auth middleware on new API routes

## MCP Servers
- **postgres** — PostgreSQL database access (read/write)
- **github** — GitHub API: issues, PRs, code search

What CLAUDE.md adds on top of AGENTS.md

CLAUDE.md starts with @AGENTS.md — Claude Code reads the canonical context file directly instead of a copy. Only Claude Code-specific additions follow the import line:

• Skill recommendations — stack-aware suggestions (e.g. test-driven-development for Vitest projects, debugging-and-error-recovery for Express APIs)
• Local commands — your project's .claude/commands/ and .claude/skills/ documented for Claude
• Management note — points to AGENTS.md as the canonical source

---

Custom Sections

Manual additions you make to any managed file survive every resync:

## Team Notes
- Payments work: check with @alice before shipping anything in src/billing/
- Use staging Stripe keys (in .env.staging) for all local testing
- The `/api/webhooks/stripe` endpoint must stay idempotent — see ADR-007

Run /agents-sync sync next week after adding three new dependencies. Your team notes are untouched. The stack section is updated.

---

Setup

Claude Code

Add to ~/.claude/claude_desktop_config.json or your project's .claude/settings.json:

{
  "mcpServers": {
    "agents-sync": {
      "command": "npx",
      "args": ["@googlarz/agents-sync"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

Restart Claude Code. Then: /agents-sync init in any project.

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "agents-sync": {
      "command": "npx",
      "args": ["@googlarz/agents-sync"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.agents-sync]
command = "npx"
args = ["@googlarz/agents-sync"]
env = { ANTHROPIC_API_KEY = "sk-ant-..." }

opencode

Add to ~/.config/opencode/config.json:

{
  "mcpServers": {
    "agents-sync": {
      "type": "local",
      "command": ["npx", "@googlarz/agents-sync"],
      "environment": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

> Codex / opencode users: agents-sync uses the Anthropic API only for init and sync. All read commands (scan, drift, derive, lint, validate, status, export) make zero API calls. The free tier at console.anthropic.com covers occasional syncs.

---

Usage

Keep context fresh — check for drift

After any significant change (new dependency, new directory, architecture shift):

npx @googlarz/agents-sync drift .

agents-sync drift report (2026-05-28)
Last sync: 12 days ago

MED   Manifest changed (dependencies or scripts updated)
HIGH  Stack contradiction: AGENTS.md states "prisma" but manifest now has drizzle-orm
      Database layer may have migrated — re-sync to update AI context

Re-sync strongly recommended. Run: /agents-sync sync

Re-sync

ANTHROPIC_API_KEY=sk-ant-... npx @googlarz/agents-sync sync .

✓ claude   → /your/project/CLAUDE.md
✓ cursor   → /your/project/.cursorrules
✓ copilot  → /your/project/.github/copilot-instructions.md

  2 custom section(s) preserved

Re-derive after manual AGENTS.md edits

Edited AGENTS.md by hand and want all tool files to reflect your changes without an API call?

npx @googlarz/agents-sync derive .

This re-runs all derivers from the current AGENTS.md content — no scanner, no Claude API. Useful after fixing a typo, adding a custom section, or tweaking a convention.

Lint — enforce your own rules

agents-sync lint checks your codebase against every mechanically-verifiable Never rule in AGENTS.md. Zero setup — the rules come from what Claude extracted about your project.

npx @googlarz/agents-sync lint .

⚠ 2 violation(s) found

  any-type   src/api/webhook.ts:34    parameter typed as 'any' — use 'unknown'
  direct-db  src/jobs/cleanup.ts:12   direct db import outside lib/db.ts

Use --ci to exit 1 in CI pipelines.

Validate — check files are in sync

npx @googlarz/agents-sync validate .           # Informational (always exits 0)
npx @googlarz/agents-sync validate . --strict  # CI gate — exits 1 when any file drifted

AGENTS.md (canonical)  ✓

✓ claude      in sync   CLAUDE.md
⚠ cursor      DRIFTED   .cursorrules  (modified after last sync)
✓ copilot     in sync   .github/copilot-instructions.md

→ Run agents-sync sync to fix.

Full CLI reference

npx @googlarz/agents-sync load-context .             # Just install the SessionStart hook (already have AGENTS.md)
npx @googlarz/agents-sync load-context --global      # Install once for ALL projects on this machine (~/.claude)
npx @googlarz/agents-sync load-context . --lazy      # + lazy subdirectory loading (monorepos)
npx @googlarz/agents-sync load-context . --anti-compaction  # + PreToolUse hook (survives context compaction)
npx @googlarz/agents-sync unload-context .           # Remove SessionStart/PreToolUse hooks
npx @googlarz/agents-sync unload-context --global    # Remove the global hook

npx @googlarz/agents-sync scan .                     # No API key — see what scanner detects
npx @googlarz/agents-sync init .                     # Generate all context files
npx @googlarz/agents-sync sync .                     # Re-sync after codebase changes
npx @googlarz/agents-sync drift .                    # Check what changed
npx @googlarz/agents-sync lint .                     # Verify codebase against Never rules
npx @googlarz/agents-sync check-spec .               # Validate AGENTS.md against cross-tool spec
npx @googlarz/agents-sync validate .                 # Check files match AGENTS.md
npx @googlarz/agents-sync validate . --strict        # Exit 1 when any file drifted (CI)
npx @googlarz/agents-sync derive .                   # Re-derive all files from AGENTS.md (no API)
npx @googlarz/agents-sync export cursor .            # Re-derive one file (no API call)
npx @googlarz/agents-sync status .                   # Show sync status

npx @googlarz/agents-sync drift . --ci               # Exit 1 on HIGH drift (CI)
npx @googlarz/agents-sync lint . --ci                # Exit 1 on any violation (CI)
npx @googlarz/agents-sync check-spec . --ci          # Exit 1 on errors only (not warnings)
npx @googlarz/agents-sync init . --dry-run           # Preview without writing
npx @googlarz/agents-sync init . --tools claude,cursor,kiro,trae  # Specific tools only
npx @googlarz/agents-sync sync . --fast              # Skip API call if drift is minor (still refreshes MCP + codegraph)

npx @googlarz/agents-sync install-hook .                        # Pre-commit + SessionStart hooks
npx @googlarz/agents-sync install-hook . --lazy                 # + lazy subdirectory loading (monorepos)
npx @googlarz/agents-sync install-hook . --anti-compaction      # + PreToolUse hook
npx @googlarz/agents-sync install-hook . --dry-run              # Preview without writing
npx @googlarz/agents-sync install-hook . --no-session-hook      # Pre-commit only
npx @googlarz/agents-sync uninstall-hook .                      # Remove both hooks

---

Hooks

install-hook does two things:

1. Pre-commit drift check — blocks commits when AI context files drift from AGENTS.md
2. Claude Code SessionStart hook — auto-loads AGENTS.md as context at the start of every Claude Code session (via .claude/settings.json)

npx @googlarz/agents-sync install-hook .
npx @googlarz/agents-sync uninstall-hook .   # Remove both hooks

Auto-detects your hook manager — husky, lefthook, or plain git hooks. Force a specific one with --husky, --lefthook, or --git. Skip the SessionStart hook with --no-session-hook.

Monorepo? Add --lazy to also install a second SessionStart entry that tell

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: googlarz
• Source: googlarz/agents-sync
• License: MIT

Install and usage instructions live in the source repository linked above.