Agents

agents

One config to rule them all.Practical standard layer for multi-LLM development.

Quick Start · Integrations · Commands · FAQ

---

The Problem

Every AI coding tool wants its own config format:

| | Codex | Claude Code | Claude Desktop | Gemini | Cursor | Copilot VS Code | Copilot CLI | Antigravity | Windsurf | OpenCode | Junie | |:--|:-----:|:-----------:|:---------------:|:------:|:------:|:---------------:|:-----------:|:-----------:|:--------:|:--------:|:-----:| | Config | .codex/config.toml | CLI commands | Global claude_desktop_config.json | .gemini/settings.json | .cursor/mcp.json | .vscode/mcp.json | .mcp.json | .agents/mcp_config.json | Global mcp_config.json | opencode.json | .junie/mcp/mcp.json | | Instructions | AGENTS.md | CLAUDE.md | — | AGENTS.md | .cursorrules | — | AGENTS.md | AGENTS.md | AGENTS.md | AGENTS.md | AGENTS.md | | Format | TOML | JSON (via CLI) | JSON | JSON | JSON | 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. For Claude Desktop, it syncs local stdio MCP servers into the global claude_desktop_config.json while preserving non-agents entries already in that file. Remote Claude MCP servers are managed by Claude custom connectors, not by this file.

---

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

Integration MCP Servers Skills Instructions How it syncs

Codex ✅ ✅ ✅ Writes .codex/config.toml

Claude Code ✅ ✅ ✅ Calls claude mcp add/remove CLI + manages root CLAUDE.md wrapper

Claude Desktop ✅ — — Writes local stdio servers to global claudedesktopconfig.json and preserves non-agents MCP entries

Gemini CLI ✅ ✅ ✅ Writes .gemini/settings.json

Cursor ✅ ✅ ✅ Writes .cursor/mcp.json + CLI enable

Copilot VS Code ✅ — — Writes .vscode/mcp.json

Copilot CLI ✅ ✅ ✅ Writes project .mcp.json; Copilot CLI reads AGENTS.md and .agents/skills natively

Antigravity ✅ ✅ ✅ Writes workspace .agents/mcp_config.json; Antigravity CLI (agy) reads AGENTS.md and .agents/skills natively

Windsurf ✅ ✅ ✅ Writes to global user profile ~/.codeium/windsurf/mcp_config.json and preserves unmanaged entries + workspace .windsurf/skills

OpenCode ✅ ✅ ✅ Writes project opencode.json (mcp block)

Junie ✅ ✅ ✅ Writes .junie/mcp/mcp.json + skills bridge .junie/skills

Antigravity note: agents manages the workspace MCP config used by Antigravity CLI. Global Antigravity editor/CLI profile files are left user-owned, and product limitations such as current Google/Google Cloud remote MCP OAuth caveats still apply.

---

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)
│   ├── mcp_config.json              ← Generated Antigravity CLI MCP (gitignored in source-only mode)
│   ├── skills/                      ← Reusable workflow definitions
│   │   └── my-skill/SKILL.md
│   └── generated/                   ← Auto-generated artifacts (gitignored)
│       ├── codex.config.toml
│       ├── claude-desktop.mcp.json
│       ├── copilot.cli.mcp.json
│       ├── gemini.settings.json
│       ├── antigravity.mcp_config.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                  │
├── .mcp.json                         │  Copilot CLI
├── .agents/mcp_config.json           │  Antigravity CLI
├── opencode.json                     │
├── .claude/skills/ → .agents/skills  │  Claude workspace bridges
├── .cursor/skills/ → .agents/skills  │
├── .gemini/skills/ → .agents/skills  │  Gemini workspace bridge
├── .windsurf/skills/ → .agents/skills│
└── .junie/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. > Claude Desktop MCP is materialized into the user's global claude_desktop_config.json, not into the project tree.

---

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 | Add a server interactively | | agents mcp add | 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 | 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  │
│                                        ├────────→ Claude     │
│                                        │          Desktop    │
│                                        │          Global JSON│
│                                        ├────────→ Gemini     │
│   ${ENV_VARS} ─── resolve ─────────────┤          JSON       │
│   ${PROJECT_ROOT}                      ├────────→ Cursor     │
│                                        │          JSON + CLI │
│                                        ├────────→ Copilot    │
│                                        │          VS Code + CLI │
│                                        ├────────→ Antigravity│
│                                        │          .agents/   │
│                                        │          mcp_config │
│                                        ├────────→ Windsurf   │
│                                        │          Global MCP │
│                                        ├────────→ OpenCode   │
│                                        │          opencode.json │
│                                        └────────→ Junie      │
│                                                   .junie/mcp/ │
│                                                              │
│   .agents/skills/ ── symlink ──→ .claude/skills              │
│                                  .cursor/skills              │
│                                  .gemini/skills              │
│                                  .junie/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 Code/Cursor, writes global configs with scoped merge/cleanup, and manages Claude Code's root CLAUDE.md wrapper
6. Bridge skills — creates symlinks from tool directories to .agents/skills/ where needed; Codex, Antigravity CLI, Copilot CLI, and OpenCode read .agents/skills/ directly

---

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 YOUR_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 Code
agents mcp add claude-only-server --url "https://..." --target claude

# Only for Claude Desktop
agents mcp add desktop-only-server --command npx --arg @my-org/server --target claude_desktop

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

# Only for Copilot CLI
agents mcp add copilot-cli-server --command npx --arg @my-org/server --target copilot_cli

---

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 YOUR_API_TOKEN"
git add .agents/agents.json .agents/skills/ AGENTS.md && git commit -m "Add agents config"

New member onboards:

git clone  && cd 
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

Does this replace AGENTS.md?

No. It extends it. AGENTS.md is human-readable guidance for LLMs; agents handles machine-readable config (MCP servers, skills) and keeps everything in sync. When Claude integration is enabled, agents also generates a minimal root CLAUDE.md wrapper that references AGENTS.md.

Can I use this with only one tool?

Yes. You still get cleaner config management, safer git defaults, secret splitting, and easy MCP server management — even for a single tool.

Where should secrets live?

In .agents/local.json (gitignored by default). The CLI automatically splits secrets from public config when you add MCP servers.

What happens during agents sync?

It reads your .agents/ config, merges secrets, resolves placeholders, generates tool-specific files, and writes them atomically. For Claude Code and Cursor it also calls their CLIs to register servers. Claude Desktop stdio servers are synced by updating its global claudedesktopconfig.json without touching non-agents MCP entries. The whole process is idempotent and safe to run repeatedly. For Claude Code it also maintains a root CLAUDE.md wrapper without duplicating the contents of AGENTS.md.

How do I keep configs in sync automatically?

Run agents watch — it polls .agents/ files and auto-syncs on changes. Or run agents sync manually after editing config.

Can I target an MCP server to specific tools only?

Yes. Add "targets": ["claude", "claude_desktop", "cursor"] to a server definition in agents.json, or use the --target flag with agents mcp add. Servers without targets stay universal and are included for integrations as they are enabled.

Any Claude Desktop caveats?

Yes. Claude Desktop local JSON sync is stdio-only. HTTP/SSE MCP servers should be added in Claude as custom connectors or wrapped by a stdio bridge. Prefer absolute paths in command/args, and avoid relying on cwd for Desktop-targeted servers.

---

Docs

| | Resource | |:--|:---------| | 📖 | [Usage Examples](docs/EXAMPLES.md) — solo dev, teams, monorepos, scripting | | 🏗️ | [System Architecture](docs/agents-system.md) — sync internals, file formats, security model | | 📋 | [Changelog](CHANGELOG.md) — version history and migration notes |

---

Community

Source & license

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

• Author: amtiYo
• Source: amtiYo/agents
• License: Apache-2.0

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