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

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=<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<!-- Generated by agents-sync v1.4.0 on 2026-05-20 -->## 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)
## Conventions1. 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
## Gotchas1. 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:

<!-- AGENTS-SYNC:CUSTOM:START -->## 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
<!-- AGENTS-SYNC:CUSTOM:END -->

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:

Pre-commit drift check — blocks commits when AI context files drift from AGENTS.md
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 tells Claude to check for an AGENTS.md whenever it enters a subdirectory it hasn't visited yet. The root AGENTS.md loads at session start; package-level AGENTS.md files load on demand:

npx @googlarz/agents-sync load-context . --lazy
# or if you're using install-hook:
npx @googlarz/agents-sync install-hook . --lazy

What it installs:

husky

# .husky/pre-commitif git diff --cached --name-only | grep -qE '(package\.json|pyproject\.toml|Cargo\.toml|go\.mod|pom\.xml|build\.gradle|Gemfile|composer\.json|AGENTS\.md|CLAUDE\.md|\.cursorrules|GEMINI\.md|\.windsurfrules|\.clinerules|\.roomodes|CONVENTIONS\.md)';then
npx @googlarz/agents-sync drift . --ci
fi

lefthook

# .lefthook.ymlpre-commit:
commands:
agents-sync:
glob: "{package.json,pyproject.toml,Cargo.toml,go.mod,pom.xml,build.gradle,Gemfile,composer.json,AGENTS.md,CLAUDE.md,.cursorrules,GEMINI.md,.windsurfrules,.clinerules,.roomodes,CONVENTIONS.md}"run: npx @googlarz/agents-sync drift . --cifail_text: "AI context files are out of sync. Run: npx @googlarz/agents-sync sync ."

plain git

# .git/hooks/pre-commitif git diff --cached --name-only | grep -qE '(package\.json|pyproject\.toml|Cargo\.toml|go\.mod|pom\.xml|build\.gradle|Gemfile|composer\.json|AGENTS\.md|CLAUDE\.md|\.cursorrules|GEMINI\.md|\.windsurfrules|\.clinerules|\.roomodes|CONVENTIONS\.md)';then
npx @googlarz/agents-sync drift . --ci
if [ $?-ne 0 ];thenecho"AI context files are out of sync. Run: npx @googlarz/agents-sync sync ."exit 1
fifi

Plain git hooks are local only — each teammate runs install-hook once. For shared enforcement, use husky or lefthook.

SessionStart (Claude Code)

// .claude/settings.json (merged, not overwritten)
{
"hooks": {
"SessionStart": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "bash -c 'r=$(git -C \"$(pwd)\" rev-parse --show-toplevel 2>/dev/null || pwd); [ -f \"$r/AGENTS.md\" ] && cat \"$r/AGENTS.md\" || true' # agents-sync"
}
]
}
]
}
}

Walks to the git root from the current working directory, so it works correctly when you open a subdirectory. Merges into existing settings.json — other hooks and settings are preserved. Uninstall removes only the agents-sync entry.

Known limitation — Claude Code appends a disclaimer to hook output. Content loaded via a SessionStart hook appears inside a <system-reminder> block, and Claude Code currently appends: "IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task." This can reduce how strictly Claude follows the rules (#18560).

The @AGENTS.md import inside CLAUDE.md (written by agents-sync init) does not get this disclaimer — it's a native file reference, not a system-reminder. If you ran agents-sync init, the @AGENTS.md import in CLAUDE.md already covers the main session without the disclaimer. The SessionStart hook adds coverage for subdirectory sessions where CLAUDE.md isn't auto-loaded; agents-sync load-context will tell you when this applies.

GitHub Action

agents-sync ships a published GitHub Action. Drop this into .github/workflows/agents-sync.yml:

name: Sync AI context fileson:
push:
paths:
- 'package.json'
- 'pyproject.toml'
- 'Cargo.toml'
- 'go.mod'
- 'pom.xml'
- 'build.gradle'schedule:
- cron: '0 9 * * 1'# Every Monday at 9 AMpermissions:
contents: writepull-requests: writejobs:
sync:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v4
- uses: googlarz/agents-sync@v1with:
anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}create-pr: true

Inputs:

Input	Default	Description
`anthropic-api-key`	(empty)	API key. When omitted, uses template mode (no cost).
`project-path`	`.`	Path to the project root
`tools`	all	Comma-separated list: `claude,cursor,copilot,…`
`fast`	`false`	Pass `--fast` to skip re-extraction on minor drift
`create-pr`	`true`	Create a PR when files are updated
`pr-title`	`chore: sync AI context files`	PR title
`version`	`latest`	agents-sync npm version to install

Outputs:changed (true/false), pr-url (URL of the created PR)

Tip:ANTHROPIC_API_KEY is optional — the action works without it using template-based generation. This means you can add the action to open-source repos where storing secrets is impractical.

For a more customized workflow, see docs/github-action.yml.

How It Works

Pipeline details

Your codebase
│
▼
[scan] package manifests · directory tree · source samples
README · FIXME/HACK/TODO comments · MCP servers · local skills
│
├── (with ANTHROPIC_API_KEY)
│ │
│ ▼
│ [generate] Claude API (claude-sonnet-4-6) — single call
│ corpus → AGENTS.md directly (no JSON intermediate)
│ ~15–30s · ~$0.03–0.06 per run
│
└── (without ANTHROPIC_API_KEY)
│
▼
[template] stack-specific template (TypeScript/Node, Python,
Go, Rust, Java, generic) filled with scanner data
0s · $0.00
│
▼
[AGENTS.md] ←── one canonical source of truth
│
├──▶ AGENTS.md (read directly by Codex CLI and opencode)
├──▶ CLAUDE.md (superset + MCP docs + skill recommendations)
├──▶ .cursorrules (directive-style, < 400 words)
├──▶ .github/copilot-instructions.md (code-level focus, < 300 words)
├──▶ GEMINI.md (full AGENTS.md + Gemini CLI section)
├──▶ .windsurfrules (directive-style, < 400 words)
├──▶ .clinerules (Always/Never sections, < 400 words)
├──▶ .roomodes (Roo Code custom modes)
├──▶ CONVENTIONS.md (Aider conventions file)
├──▶ .kiro/steering/agents-sync.md (Kiro IDE steering doc)
└──▶ .trae/rules/agents-sync.md (Trae IDE rules)

The scanner and all derivers run entirely locally. Only the generate step calls the API (single call). Drift detection, validation, lint, export, derive, and template mode are all local.

Troubleshooting

"ANTHROPIC_API_KEY not set"init and sync now work without a key — they fall back to stack-specific templates (TypeScript/Node, Python, Go, Rust, Java). Add ANTHROPIC_API_KEY to switch to AI-powered output.

Other commands (scan, drift, validate, status, export, derive, lint) never need a key.

"My AGENTS.md looks wrong / missed something important" Run agents-sync sync . to regenerate from the current codebase state. If the scanner missed something structural, check that your project has a recognizable manifest file (package.json, pyproject.toml, Cargo.toml, go.mod).

"I edited CLAUDE.md manually and sync overwrites my changes" Wrap your additions in a custom section:

<!-- AGENTS-SYNC:CUSTOM:START -->
your content here
<!-- AGENTS-SYNC:CUSTOM:END -->

Everything inside those markers survives every sync.

"Drift says HIGH but I only changed one file" Drift scores are based on structural signals (new dependencies, new directories, naming pattern changes). A single package.json change that adds a major dependency triggers HIGH. That's intentional — architecture assumptions may need updating.

"How much does each sync cost?" Typically $0.05–0.10 using claude-sonnet-4-6. Syncs on previously-indexed projects are cheaper due to prompt caching. Use --fast to skip the API call entirely when drift is minor.

Team Config — `agents-sync.config.json`

Pin tools and override extraction results for your whole team. Drop a file at the project root:

{
"tools": ["claude", "cursor", "copilot", "kiro"],
"project": {
"name": "my-app",
"description": "Internal analytics dashboard"
},
"conventions": [
"All API routes must have an OpenAPI annotation"
],
"boundaries": {
"never": ["Merge to main without a passing CI run"]
}
}

tools — limit which files get generated (omit to generate all)
project, conventions, boundaries — override/extend Claude's extracted values

The config is loaded on every init/sync. Changes take effect on the next sync.

Environment Variables

Variable	Required	Description
`ANTHROPIC_API_KEY`	For `init` and `sync` only	Your Anthropic API key
`AGENTS_SYNC_MODEL`	No	Override the Claude model (e.g. `claude-haiku-4-5-20251001` for faster/cheaper runs)
`AGENTS_SYNC_DEBUG=1`	No	Verbose debug output to stderr
`NO_COLOR=1`	No	Disable ANSI color

scan, drift, derive, validate, status, export, and lint never call the API.

MCP Tools Reference

Tool	Description
`agents_sync_scan`	Show what scanner detected — no API key needed
`agents_sync_init`	Full init: scan, extract, generate, derive, snapshot
`agents_sync_sync`	Re-sync from current codebase state
`agents_sync_drift`	Check what changed since last sync (read-only)
`agents_sync_derive`	Re-derive all tool files from AGENTS.md (no API call)
`agents_sync_export`	Re-derive a single tool file (no API call)
`agents_sync_validate`	Check if all tool files match AGENTS.md
`agents_sync_status`	Show sync status and managed files
`agents_sync_lint`	Verify codebase against Never rules in AGENTS.md
`agents_sync_load_context`	Install ONLY the SessionStart hook; pass `global: true` to cover all projects on the machine, `lazy: true` for monorepos
`agents_sync_unload_context`	Remove SessionStart/PreToolUse hooks
`agents_sync_check_spec`	Validate AGENTS.md against cross-tool spec
`agents_sync_install_hook`	Install pre-commit hook + Claude Code SessionStart hook
`agents_sync_uninstall_hook`	Remove both agents-sync hooks

Claude Code Skill

Use agents-sync as a Claude Code skill — invoke agents-sync directly in conversation:

# Install the skill
cp -r skill ~/.claude/skills/agents-sync

Then in Claude Code: /agents-sync init, /agents-sync sync, /agents-sync drift.

Supported Stacks

TypeScript/JavaScript: Next.js, Express, Fastify, Remix, SvelteKit, Vite
Python: Django, FastAPI, Flask
Rust: Cargo workspaces, Axum, Actix
Go: standard modules, Gin, Echo
PHP: Composer projects, Laravel

Language-agnostic — works on any codebase with a manifest file.

Related Tools

cc-safe-setup — pioneered the agents-md-loader SessionStart hook pattern that agents-sync now ships natively via install-hook. If you only want the SessionStart hook without the full agents-sync pipeline, cc-safe-setup is a lighter option. For teams who also want AGENTS.md generation, drift detection, and 11-tool derivation, agents-sync install-hook . covers everything in one command.

cc-agents-md — patches the Claude Code JavaScript directly so it reads AGENTS.md natively alongside CLAUDE.md, without any hook. Works until the next Claude Code update (needs re-patching after upgrades). Use if you want the absolute minimum setup and are comfortable reapplying the patch on CC updates. agents-sync takes the opposite approach: works with Claude Code's documented hook and @-import mechanisms, so it never breaks on updates.

Contributing

git clone https://github.com/googlarz/agents-sync
cd agents-sync
npm install
npm run dev # watch mode
npm test# 248 unit tests, no API key needed

Integration tests (require ANTHROPIC_API_KEY, run against real fixtures):

npm run test:integration

License

MIT

Built for the vibe coding era — when your AI tools should know your codebase as well as you do.

Report a bug · Request a feature · Roadmap

Name		Name	Last commit message	Last commit date
.github		.github
docs		docs
scripts		scripts
skill		skill
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
action.yml		action.yml
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

agents-sync

The Problem

Why Not Just Write CLAUDE.md Once?

Quick Start

What Gets Generated

Custom Sections

Setup

Claude Code

Cursor

Codex CLI

opencode

Usage

Keep context fresh — check for drift

Re-sync

Re-derive after manual AGENTS.md edits

Lint — enforce your own rules

Validate — check files are in sync

Hooks

GitHub Action

How It Works

Troubleshooting

Team Config — `agents-sync.config.json`

Environment Variables

Claude Code Skill

Supported Stacks

Related Tools

Contributing

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

agents-sync

The Problem

Why Not Just Write CLAUDE.md Once?

Quick Start

What Gets Generated

Custom Sections

Setup

Claude Code

Cursor

Codex CLI

opencode

Usage

Keep context fresh — check for drift

Re-sync

Re-derive after manual AGENTS.md edits

Lint — enforce your own rules

Validate — check files are in sync

Hooks

GitHub Action

How It Works

Troubleshooting

Team Config — agents-sync.config.json

Environment Variables

Claude Code Skill

Supported Stacks

Related Tools

Contributing

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Team Config — `agents-sync.config.json`