The Problem

Every AI coding tool wants its own config format:

| | Codex | Claude | Gemini | Cursor | Copilot | Antigravity | Windsurf | OpenCode | |:--|:-----:|:------:|:------:|:------:|:-------:|:-----------:|:--------:|:--------:| | Config | .codex/config.toml | CLI commands | .gemini/settings.json | .cursor/mcp.json | .vscode/mcp.json | Global mcp.json | Global mcp_config.json | opencode.json | | Instructions | AGENTS.md | CLAUDE.md | AGENTS.md | .cursorrules | — | AGENTS.md | AGENTS.md | AGENTS.md | | Format | TOML | JSON (via CLI) | JSON | JSON | JSON | JSON | JSON | JSON |

Result: Duplicated configs, team drift, painful onboarding.

agents gives you one source of truth in .agents/ and syncs MCP servers, skills, and instructions to every tool automatically. For Claude Code, it keeps AGENTS.md canonical and generates a minimal root CLAUDE.md wrapper (@AGENTS.md) when the Claude integration is enabled.

Quick Start

# 1. Install
npm install -g @agents-dev/cli

# 2. Interactive setup — picks integrations, adds MCP servers, syncs everything
agents start

# 3. Re-sync whenever config changes
agents sync

That's it. Your .agents/agents.json is now the single source of truth.

Using agents in this repository

This repository uses @agents-dev/cli to keep MCP servers, skills, and instructions aligned across supported AI tools.

Quick commands

agents status
agents mcp add <url-or-name>
agents mcp test --runtime
agents sync
agents sync --check

One MCP setup for all tools

Add a server once in .agents/agents.json, then run agents sync to materialize it for enabled integrations.

References

• MCP Protocol Docs: https://modelcontextprotocol.io
• MCP servers catalog: https://mcpservers.org
• Project examples: docs/EXAMPLES.md

Supported Integrations

Project Layout

your-project/
├── AGENTS.md                        ← Canonical instructions for all tools
├── CLAUDE.md                        ← Generated Claude wrapper (`@AGENTS.md`)
├── .agents/
│   ├── agents.json                  ← MCP servers & config (commit this)
│   ├── local.json                   ← Secrets & overrides (gitignored)
│   ├── skills/                      ← Reusable workflow definitions
│   │   └── my-skill/SKILL.md
│   └── generated/                   ← Auto-generated artifacts (gitignored)
│       ├── codex.config.toml
│       ├── gemini.settings.json
│       ├── cursor.mcp.json
│       ├── windsurf.mcp.json
│       ├── opencode.json
│       └── ...
│
│  ┌─── Generated by `agents sync` ───┐
├── .codex/config.toml                │  Materialized tool configs
├── .gemini/settings.json             │  (gitignored in source-only mode)
├── .cursor/mcp.json                  │
├── .vscode/mcp.json                  │
├── opencode.json                     │
├── .claude/skills/ → .agents/skills  │  Claude workspace bridges
├── .cursor/skills/ → .agents/skills  │
├── .gemini/skills/ → .agents/skills  │
└── .windsurf/skills/ → .agents/skills│

Git strategy: By default only .agents/agents.json, .agents/skills/, and AGENTS.md are committed. Generated CLAUDE.md and tool-specific outputs are gitignored in source-only mode and regenerated with agents sync.

Command Overview

Setup & Sync

| Command | Description | |:--------|:------------| | agents start | Interactive setup wizard — integrations, MCP servers, skills, first sync | | agents start --inject-docs | Also upsert an agents guide block in README.md (+ CONTRIBUTING.md if present) | | agents start --reinit | Reinitialize existing .agents/agents.json with fresh wizard/default choices | | agents init | Scaffold .agents/ directory without guided setup | | agents sync | Regenerate and materialize all tool configs | | agents sync --check | Strict read-only drift check — exits 2 if config is out of sync | | agents watch | Auto-sync on .agents/ file changes (--once exits non-zero on sync failure) |

Diagnostics

| Command | Description | |:--------|:------------| | agents status | Show integrations, MCP servers, file states, and live probes | | agents status --fast | Skip external CLI probes for quicker output | | agents doctor | Validate configs, check for issues, suggest fixes | | agents doctor --fix | Auto-fix what can be fixed | | agents update | Check for newer CLI version on npm |

MCP Server Management

| Command | Description | |:--------|:------------| | agents mcp add <name> | Add a server interactively | | agents mcp add <url> | Import a server from URL (mcpservers.org, GitHub, etc.) | | agents mcp import --file config.json | Bulk import from JSON/JSONC file | | agents mcp list | List all configured servers | | agents mcp remove <name> | Remove a server (--no-sync skips auto-sync for add/import/remove) | | agents mcp test | Validate server definitions | | agents mcp test --runtime | Live connectivity check via tool CLIs |

Integrations

| Command | Description | |:--------|:------------| | agents connect --llm cursor,claude | Add integrations to the currently enabled set | | agents disconnect --llm codex | Disable integrations | | agents reset | Remove generated files, keep .agents/ | | agents reset --hard | Full cleanup — removes all agents-managed setup |

How It Works

┌──────────────────────────────────────────────────────────────┐
│                      agents sync                             │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│   .agents/agents.json ─── merge ──→ Resolved    ──→ Codex   │
│         (shared)           ↑        Registry          TOML   │
│                            │           │                     │
│   .agents/local.json ──────┘           ├────────→ Claude     │
│      (secrets)                         │          CLI + root │
│                                        │          CLAUDE.md  │
│                                        ├────────→ Gemini     │
│   ${ENV_VARS} ─── resolve ─────────────┤          JSON       │
│   ${PROJECT_ROOT}                      ├────────→ Cursor     │
│                                        │          JSON + CLI │
│                                        ├────────→ Copilot    │
│                                        │          VS Code    │
│                                        ├────────→ Antigravity│
│                                        │          Global     │
│                                        ├────────→ Windsurf   │
│                                        │          Global MCP │
│                                        └────────→ OpenCode   │
│                                                   opencode.json │
│                                                              │
│   .agents/skills/ ── symlink ──→ .claude/skills              │
│                                  .cursor/skills              │
│                                  .gemini/skills              │
│                                  .windsurf/skills            │
└──────────────────────────────────────────────────────────────┘

1. Load — reads .agents/agents.json + merges secrets from .agents/local.json
2. Resolve — expands ${PROJECT_ROOT}, ${ENV_VAR} placeholders, filters by enabled and requiredEnv
3. Route — sends each server to its target integrations (or all, if no targets specified)
4. Generate — renders tool-specific config formats (TOML for Codex, JSON for others)
5. Materialize — writes configs atomically (project-local and global targets), calls CLIs for Claude/Cursor, and manages Claude's root CLAUDE.md wrapper
6. Bridge skills — creates symlinks from tool directories to .agents/skills/ (including Windsurf workspace bridge)

MCP Server Examples

Add from mcpservers.org

agents mcp add https://mcpservers.org/servers/context7-mcp

Add a stdio server

agents mcp add my-server \
  --command npx \
  --arg @my-org/mcp-server \
  --arg /path/to/project

Add an HTTP server with secrets

agents mcp add company-api \
  --url "https://api.company.com/mcp" \
  --secret-header "Authorization=Bearer {{API_TOKEN}}"

Secrets are automatically detected and split: placeholders go to agents.json (committed), real values to local.json (gitignored).

Target specific tools

# Only for Claude
agents mcp add claude-only-server --url "https://..." --target claude

# Only for Cursor and Copilot
agents mcp add ide-server --command ide-mcp --target cursor --target copilot_vscode

Security

| | What | Where | |:--|:-----|:------| | 🔓 | Server definitions, team config | .agents/agents.json — committed | | 🔒 | API keys, tokens, secrets | .agents/local.json — gitignored |

How secrets work:

• When you add a server, agents detects secret-like values (API keys, tokens, JWTs)
• Secrets are moved to local.json and replaced with ${PLACEHOLDER} in agents.json
• agents doctor warns if it finds literal secrets in committed config
• All env keys and header names are validated to prevent injection

Team Workflow

Lead sets up the project:

agents start
agents mcp add https://mcpservers.org/servers/context7-mcp
agents mcp add company-api --url "https://api.company.com/mcp" \
  --secret-header "Authorization=Bearer {{API_TOKEN}}"
git add .agents/agents.json .agents/skills/ AGENTS.md && git commit -m "Add agents config"

New member onboards:

git clone <repo> && cd <repo>
agents start        # Preserves team config and syncs local tool files
# Add your local secrets in .agents/local.json if required by project MCP servers

One command. Same MCP servers, same skills, same instructions. No drift.

FAQ

Docs

| | Resource | |:--|:---------| | 📖 | Usage Examples — solo dev, teams, monorepos, scripting | | 🏗️ | System Architecture — sync internals, file formats, security model | | 📋 | Changelog — version history and migration notes |

Community