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	Gemini	Cursor	Copilot	Antigravity	Windsurf	OpenCode	Junie
Config	`.codex/config.toml`	CLI commands	`.gemini/settings.json`	`.cursor/mcp.json`	`.vscode/mcp.json`	Global `mcp.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`
Format	TOML	JSON (via CLI)	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.

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

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
Gemini CLI	✅	✅	✅	Writes `.gemini/settings.json`
Cursor	✅	✅	✅	Writes `.cursor/mcp.json` + CLI enable
Copilot	✅	✅	✅	Writes `.vscode/mcp.json`
Antigravity	✅	✅	✅	Writes to global user profile `mcp.json`
Windsurf	✅	✅	✅	Writes to global user profile `~/.codeium/windsurf/mcp_config.json` + workspace `.windsurf/skills`
OpenCode	✅	✅	✅	Writes project `opencode.json` (`mcp` block)
Junie	✅	✅	✅	Writes `.junie/mcp/mcp.json` + skills bridge `.junie/skills`

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 │
│                                        └────────→ Junie      │
│                                                   .junie/mcp/ │
│                                                              │
│   .agents/skills/ ── symlink ──→ .claude/skills              │
│                                  .cursor/skills              │
│                                  .gemini/skills              │
│                                  .junie/skills               │
│                                  .windsurf/skills            │
└──────────────────────────────────────────────────────────────┘

Load — reads .agents/agents.json + merges secrets from .agents/local.json
Resolve — expands ${PROJECT_ROOT}, ${ENV_VAR} placeholders, filters by enabled and requiredEnv
Route — sends each server to its target integrations (or all, if no targets specified)
Generate — renders tool-specific config formats (TOML for Codex, JSON for others)
Materialize — writes configs atomically (project-local and global targets), calls CLIs for Claude/Cursor, and manages Claude's root CLAUDE.md wrapper
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

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 and Cursor it also calls their CLIs to register servers. The whole process is idempotent and safe to run repeatedly. For Claude 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", "cursor"] to a server definition in agents.json, or use the --target flag with agents mcp add. Servers without targets go to all enabled integrations.

Docs

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

Community

Issues Discussions npm Release History

Version	Changes	Urgency	Date
v0.8.9	### Changed - Antigravity sync now targets the current Antigravity CLI workspace MCP file (`.agents/mcp_config.json`) using `serverUrl` for remote MCP servers. - Antigravity integration preflight now checks the `agy` CLI binary instead of the older `antigravity` command name. - Antigravity-enabled projects now rely on native `.agents/skills` discovery instead of creating a `.gemini/skills` bridge when Gemini itself is not enabled. ### Fixed - Antigravity sync preserves unmanaged entries in `	High	5/30/2026
v0.8.8	### Added - New integration: Claude Desktop (`claude_desktop`) — MCP servers synced to Claude Desktop's global `claude_desktop_config.json`. - New integration: Copilot CLI (`copilot_cli`) — MCP servers synced to project `.mcp.json`; `AGENTS.md` and `.agents/skills` are used natively by Copilot CLI. - New generated artifact: `.agents/generated/claude-desktop.mcp.json`. - New generated artifact: `.agents/generated/copilot.cli.mcp.json`. - New `AGENTS_CLAUDE_DESKTOP_CONFIG_PATH` override	High	5/17/2026
v0.8.7	## Added - New integration: Junie (JetBrains) — MCP servers synced to `.junie/mcp/mcp.json`, skills bridged to `.junie/skills/`. ## Fixed - Fixed `agents sync` dropping `cwd` from generated MCP configs for all tools (Codex, Gemini, VS Code, Cursor, Copilot, Antigravity, Windsurf, OpenCode, Junie). Closes #11.	Medium	3/23/2026
v0.8.6	### Added - New `agents start --reinit` flag for explicit project config reinitialization from the start flow. - New `agents start --inject-docs` flag for non-interactive/CI flows to upsert an agents usage guide block into project docs. - New starter skills in template scaffold: - `docs-research` - `mcp-troubleshooting` - New integration coverage for stability fixes: - repeated `agents start` preserves existing config by default - `agents start --reinit` resets to selected/default setu	Low	3/8/2026
v0.8.5	### Fixed - `agents sync` no longer rewrites `lastSync` after `agents reset` or other output-only regeneration when source inputs did not change. - `agents sync --check` now reports `.agents/agents.json` as changed when source-state fingerprint backfill/update would occur in a real sync.	Low	3/7/2026
v0.8.4	### Changed - Project licensing has been switched from MIT to Apache 2.0, and a `NOTICE` file is now included. ### Fixed - Claude integration now manages a root `CLAUDE.md` wrapper that references canonical `AGENTS.md` without duplicating instructions. - `agents sync`, `agents status`, `agents doctor`, and `agents reset` now distinguish between agents-managed `CLAUDE.md` wrappers and custom user-owned `CLAUDE.md` files. - `agents sync` no longer updates `lastSync` on idempotent runs when no	Low	3/6/2026
v0.8.3	### Added - New integrations: - Windsurf MCP sync to global `~/.codeium/windsurf/mcp_config.json` - OpenCode MCP sync to project `opencode.json` - Windsurf skills bridge support via `.windsurf/skills` (linked from `.agents/skills`). - New renderer support for: - Windsurf `mcpServers` payload format - OpenCode top-level `mcp` payload with `local`/`remote` server modes - New tests: - `tests/windsurf-opencode.integration.test.ts` - expanded renderer, MCP routing, target parsin	Low	2/18/2026
v0.8.2	### Added - New `agents update` command: - human-readable version check - `--json` machine-readable output - `--check` exit-code mode (`0` up-to-date, `10` outdated, `1` check failure) - New release workflow: `.github/workflows/release.yml` (manual publish + GitHub release notes from changelog). - New test suites: - `tests/update-check.test.ts` - `tests/update.command.test.ts` ### Changed - CLI now performs update availability checks before commands and prints a hint when a newer v	Low	2/17/2026
v0.8.1	## @agents-dev/cli v0.8.1 ### Fixed - `agents start` now preserves an existing root `AGENTS.md` during force scaffold refresh. - `agents init --force` now preserves an existing root `AGENTS.md`. - Added safety handling for non-regular `AGENTS.md` paths (`symlink` / `directory`): scaffold skips overwrite and emits a warning. ### Added - New integration tests for AGENTS.md overwrite protection: - `tests/init.integration.test.ts` - Extended `tests/start-sync.integration.test.ts` ### Notes -	Low	2/14/2026
v0.8.0	## Added - New centralized UI module (`src/core/ui.ts`) with Unicode symbols, colors, and spinners - Spinners for all async commands (doctor, sync, init, reset, mcp add/remove/test) - Layout helpers: `keyValue()`, `list()`, `statusList()`, `section()`, `hint()`, `nextSteps()` - Context-aware output (respects `--json`, `--quiet`, `NO_COLOR`) ## Changed - Migrated `connect` and `disconnect` commands from `prompts` to `@clack/prompts` - Removed `prompts` dependency - Unified output formatting acro	Low	2/9/2026
v0.7.7	`@agents-dev/cli` is now public. Installation: ```bash npm install -g @agents-dev/cli ``` Quick Start: ```bash cd your-project agents start agents sync ``` Key features in this release: - Single source of truth: `.agents/` - MCP Sync for Codex, Claude Code, Gemini CLI, Cursor, Copilot, Antigravity - Full MCP workflow: add/import/test/remove - Deterministic sync + atomic writes + lockfile protection Links: - GitHub: https://github.com/amtiYo/agents - npm: https://www.npm	Low	2/7/2026

agents

Description

README

agents

The Problem

Quick Start

Using agents in this repository

Quick commands

One MCP setup for all tools

References

Supported Integrations

Project Layout

Command Overview

Setup & Sync

Diagnostics

MCP Server Management

Integrations

How It Works

MCP Server Examples

Add from mcpservers.org

Add a stdio server

Add an HTTP server with secrets

Target specific tools

Security

Team Workflow

FAQ

Docs

Community

Dependencies & License Audit

Similar Packages

More in MCP Servers