@agents-dev/cli weekly downloads statistics

agents

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

Quick Start · Integrations · Commands · Plugins · FAQ

The Problem

Instructions converged on AGENTS.md and skills converged on SKILL.md. MCP server configuration did not. Every tool keeps its own file, in its own format, in its own place:

| Format | Tools | |:--|:--| | TOML, mcp_servers tables | Codex (.codex/config.toml), Grok Build (.grok/config.toml) | | JSON, mcpServers key | Claude Code and Copilot CLI (.mcp.json), Claude Desktop (global), Gemini CLI (.gemini/settings.json), Cursor (.cursor/mcp.json), Antigravity (.agents/mcp_config.json), Devin Desktop (global), Devin CLI (.devin/mcp_config.json), Junie (.junie/mcp/mcp.json), Factory Droid (.factory/mcp.json) | | JSON, another key | Copilot VS Code (servers), OpenCode and Kilo (mcp), Amp (amp.mcpServers), Zed (context_servers) | | YAML | Goose (extensions in ~/.config/goose/config.yaml) |

Add a server by hand and you write it 18 times, then watch the copies drift apart.

agents keeps one source of truth in .agents/ and materializes it for every tool you enable.

Quick Start

.agents/agents.json is now the single source of truth. agents sync --check exits 2 when a tool config has drifted, so it works as a CI gate.

Supported Integrations

Eighteen tools. "Verified" means the tool's own CLI was run against the file this project writes; the rest follow vendor documentation and are worth reporting on if something is off.

| Integration | --llm id | MCP config it writes | Skills | Verified | |:--|:--|:--|:--:|:--:| | Codex | codex | .codex/config.toml (managed block, project trust handled) | native | ✅ | | Claude Code | claude | .mcp.json project scope, plus root CLAUDE.md wrapper | bridge | ✅ | | Claude Desktop | claude_desktop | global claude_desktop_config.json, stdio servers only | — | ✅ | | Gemini CLI | gemini | .gemini/settings.json | bridge | ✅ | | Cursor | cursor | .cursor/mcp.json + CLI enable | bridge | ✅ | | Copilot VS Code | copilot_vscode | .vscode/mcp.json | native | ✅ | | Copilot CLI | copilot_cli | .mcp.json, or .github/mcp.json | native | ✅ | | Antigravity | antigravity | .agents/mcp_config.json | flat copy | ✅ | | Devin Desktop (Windsurf) | windsurf, devin_desktop | global ~/.codeium/windsurf/mcp_config.json | bridge | ✅ | | OpenCode | opencode | opencode.json (mcp) | native | ✅ | | Junie | junie | .junie/mcp/mcp.json | bridge | ✅ | | Grok Build | grok | .grok/config.toml (managed block, folder trust handled) | native | ✅ | | Amp | amp | .amp/settings.json (amp.mcpServers) | native | ✅ | | Factory Droid | droid, factory | .factory/mcp.json | native | ✅ | | Kilo | kilo, kilocode | .kilo/kilo.jsonc (mcp) | bridge | — | | Devin CLI | devin | .devin/mcp_config.json | native | ✅ | | Zed | zed | .zed/settings.json (context_servers) | native | — | | Goose | goose | ~/.config/goose/config.yaml (extensions) | native | ✅ |

Skills column. bridge means a symlink from the tool's directory to .agents/skills (a copy where symlinks are unavailable). native means the tool reads .agents/skills itself, so nothing is created. — means the tool's project-level skill location is not implemented here.

Grok folder trust. Grok ignores a project's MCP servers and its skills until the folder is trusted, and says nothing about it: grok inspect simply lists none. Trust lives in ~/.grok/trusted_folders.toml, separate from config.toml. agents doctor reports an untrusted folder and agents doctor --fix records the trust.

Shared files. .mcp.json is read by both Claude Code and Copilot CLI, so agents writes it once for both. A server targeted at only one of them is still visible to the other; the sync says so rather than pretending targets isolate it.

Goose secrets. Goose reads credentials from the environment through env_keys, so values are never written into its config. The sync lists which variables have to exist in your shell.

Project Layout

Git strategy. In the default source-only mode, only .agents/agents.json, .agents/skills/ and AGENTS.md are committed: everything the sync generates is gitignored and rebuilt from them. In commit-generated mode the generated files stay out of .gitignore, so a clone gets working tool configs without installing this CLI. That is how you commit .mcp.json for the rest of the team.

Either way, files that hold a tool's own settings (.zed/settings.json, .amp/settings.json, .kilo/kilo.jsonc) and .github/mcp.json are never added to .gitignore: the sync merges its entries into them and leaves the rest of the file, including whether you track it, to you.

Command Overview

Setup & Sync

| Command | Description |

| agents start | Interactive setup: integrations, MCP servers, skills, first sync | | agents init | Scaffold .agents/ without the wizard | | agents sync | Regenerate and materialize all tool configs | | agents sync --check | Read-only drift check, exits 2 when out of sync | | agents sync --profile ci | Sync one profile without changing the active one | | agents watch | Auto-sync on .agents/ changes |

Diagnostics

| Command | Description |

| agents status | Integrations, MCP servers, file states, live probes | | agents doctor | Validate configs and report problems | | agents doctor --fix | Apply the fixes it can make safely | | agents update | Check npm for a newer CLI |

MCP Servers

| Command | Description |

| agents mcp add | Add a server interactively or from a URL | | agents mcp import --file config.json | Bulk import from JSON/JSONC | | agents mcp list | List configured servers | | agents mcp remove | Remove a server | | agents mcp test [--runtime] | Validate definitions, optionally through tool CLIs | | agents mcp budget | Connect to each server and measure its context cost |

Profiles

| Command | Description |…

Description from the npm listing.