@agents-dev/cli

v0.8.9

Published

a month ago

One config to rule them all — sync MCP servers, skills, and AGENTS.md across Codex, Claude Code/Desktop, Gemini CLI, Cursor, Copilot VS Code/CLI, Antigravity, Windsurf, OpenCode, and Junie.

Downloads

3,346

The Problem

Every AI coding tool wants its own config format:

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

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 <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  │
│                                        ├────────→ 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            │
└──────────────────────────────────────────────────────────────┘

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 Code/Cursor, writes global configs with scoped merge/cleanup, and manages Claude Code's root CLAUDE.md wrapper
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 <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 |