Agents Sync

agents-sync

Generate and sync AI context files across every coding tool you use.

Prerequisites

Add to your Claude Code MCP config (.claude/settings.json or ~/.claude/claude_desktop_config.json):

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

Then restart Claude Code to connect.

Commands

/agents-sync init

First-time setup. Reads your codebase and generates all context files.

When to use: New project, or starting from scratch.

What it does:

1. Scans your codebase (manifests, structure, source samples, docs, TODO/FIXME comments)
2. Extracts project metadata via Claude API
3. Generates canonical AGENTS.md
4. Derives CLAUDE.md, .cursorrules, .github/copilot-instructions.md, GEMINI.md, .windsurfrules, .clinerules, .roomodes, CONVENTIONS.md, .kiro/steering/agents-sync.md, .trae/rules/agents-sync.md
5. Saves a snapshot for drift detection

Usage:

Run /agents-sync init on this project

Claude will call agents_sync_init with the current project path.

/agents-sync sync

Re-sync after your codebase has changed. Preserves any manual customizations.

When to use: After major refactors, new dependencies, architecture changes.

Options:

• Add --fast to skip Claude API call when drift is minor (re-derives from existing AGENTS.md, still refreshes MCP + codegraph sections for free)
• Add --dry-run to preview changes without writing

Usage:

Sync my AI context files /agents-sync sync --fast

/agents-sync derive

Re-derive all tool files from the current AGENTS.md without re-running the scanner or calling the Claude API.

When to use: After manually editing AGENTS.md and wanting all tool files to reflect the changes immediately.

Usage:

/agents-sync derive I edited AGENTS.md, update all tool files

/agents-sync drift

Check what changed in your codebase since the last sync. Read-only.

Usage:

What's drifted in my AI context files? /agents-sync drift

/agents-sync export [tool]

Re-derive a single tool file without re-running analysis.

Tools: claude, cursor, copilot, gemini, windsurf, cline, roo, aider, kiro, trae

Usage:

/agents-sync export cursor Regenerate just my .cursorrules /agents-sync export kiro

/agents-sync validate

Check whether all managed files are in sync with AGENTS.md.

Usage:

/agents-sync validate Are my AI context files in sync?

/agents-sync lint

Verify the codebase against mechanically-checkable Never rules in AGENTS.md.

Usage:

/agents-sync lint

/agents-sync status

Show sync status: last sync time, managed files, drift score.

Usage:

/agents-sync status

/agents-sync scan

Show what the scanner detected — language, framework, dependencies, MCP servers. No API key needed.

Usage:

/agents-sync scan

/agents-sync install-hook

Install two hooks:

1. Pre-commit — blocks commits when AI context files have drifted (auto-detects husky, lefthook, or plain git)
2. Claude Code SessionStart — writes .claude/settings.json hook that auto-loads AGENTS.md as context at session start

Use --no-session-hook to install only the pre-commit hook.

Usage:

/agents-sync install-hook

How Claude Should Handle These Commands

When the user types /agents-sync <command>, call the corresponding MCP tool:

Determine projectPath: Use the current working directory. If ambiguous, ask the user which project to target.

If MCP not connected: Respond with:

agents-sync MCP server is not connected. Add this to your Claude Code settings and restart:

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

After init: Remind the user to:

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

After sync: Show the list of files updated.

Flags parsing:

• --fast → set fast: true in agents_sync_sync
• --dry-run → set dryRun: true
• --strict / --ci → set strict: true in agents_sync_validate

Custom Sections

Users can add permanent customizations to any managed file that survive re-syncs:

<!-- AGENTS-SYNC:CUSTOM:START -->
When working on the payments module, always check with @alice first.
Use staging Stripe keys (in .env.staging) for all local testing.
<!-- AGENTS-SYNC:CUSTOM:END -->

Add this anywhere in AGENTS.md, CLAUDE.md, .cursorrules, etc. Re-sync preserves it.