# Agents Sync

> A single source of truth for AI coding context, kept consistent across Claude Code, Cursor, Copilot, Gemini, and more as your stack evolves.

- **Type:** MCP server
- **Install:** `agentstack add mcp-googlarz-agents-sync`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [googlarz](https://agentstack.voostack.com/s/googlarz)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [googlarz](https://github.com/googlarz)
- **Source:** https://github.com/googlarz/agents-sync

## Install

```sh
agentstack add mcp-googlarz-agents-sync
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/anthropics/claude-code/issues/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](https://github.com/anthropics/claude-code/issues/40459) — 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](https://github.com/yurukusa/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:

```bash
# 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):**

```bash
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:

```bash
npx @googlarz/agents-sync init .
```

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

```bash
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

```markdown
# 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:

```markdown

## 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`:

```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:

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

### Codex CLI

Add to `~/.codex/config.toml`:

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

### opencode

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

```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](https://console.anthropic.com/) covers occasional syncs.

---

## Usage

### Keep context fresh — check for drift

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

```bash
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

```bash
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?

```bash
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.

```bash
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

```bash
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

```bash
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`)

```bash
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](https://github.com/googlarz)
- **Source:** [googlarz/agents-sync](https://github.com/googlarz/agents-sync)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-googlarz-agents-sync
- Seller: https://agentstack.voostack.com/s/googlarz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.