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

# 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

.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

your-project/
├── AGENTS.md                        ← Canonical instructions for all tools
├── CLAUDE.md                        ← Generated Claude wrapper (`@AGENTS.md`)
├── .agents/
│   ├── agents.json                  ← MCP servers, profiles, config (commit this)
│   ├── local.json                   ← Secrets & overrides (gitignored)
│   ├── mcp_config.json              ← Generated Antigravity workspace MCP
│   ├── skills/                      ← Reusable workflow definitions
│   │   └── my-skill/SKILL.md
│   └── generated/                   ← Auto-generated artifacts (gitignored)
│
│  ┌─── Generated by `agents sync` ───┐
├── .mcp.json                         │  Claude Code + Copilot CLI
├── .codex/config.toml                │  Codex
├── .grok/config.toml                 │  Grok Build
├── .gemini/settings.json             │  Gemini CLI
├── .cursor/mcp.json                  │  Cursor
├── .vscode/mcp.json                  │  Copilot VS Code
├── .amp/settings.json                │  Amp
├── .factory/mcp.json                 │  Factory Droid
├── .kilo/kilo.jsonc                  │  Kilo
├── .devin/mcp_config.json            │  Devin CLI
├── .zed/settings.json                │  Zed
├── opencode.json                     │  OpenCode
├── .junie/mcp/mcp.json               │  Junie
└── .claude/skills → .agents/skills   │  Skill bridges

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 <name\|url>`	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 <name>`	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
`agents profile set ci --server docs --server git`	Create or replace a profile
`agents profile use ci`	Activate a profile and sync
`agents profile use`	Clear the profile, back to every server
`agents profile list`	Show profiles and the active one
`agents profile remove ci`	Delete a profile

Plugins

Command	Description
`agents plugin export --name my-stack`	Build an Agent Plugins v1 package from `.agents`
`agents plugin validate <dir>`	Check a package against the specification
`agents plugin import <dir>`	Add a package's servers and skills to this project

Skills & Integrations

Command	Description
`agents skills list`	List skills found under `.agents/skills/`
`agents connect --llm cursor,grok`	Enable integrations
`agents disconnect --llm codex`	Disable integrations
`agents reset`	Remove generated files, keep `.agents/`
`agents reset --hard`	Full cleanup

Global Mode

Run any command with --global (or -g, or from $HOME) to manage MCP servers and skills machine-wide from ~/.agents/agents.json:

agents init -g
agents connect -g --llm opencode,codex,grok
agents sync -g

Tools that only have a user-level config (Claude Desktop, Devin Desktop, Goose) are written there in both modes.

Agent Plugins

Agent Plugins 1.0.0 is a vendor-neutral package format for skills and MCP servers, read by ChatGPT and Codex, Cursor, GitHub Copilot, Kiro and VS Code. A package is a directory with plugin.json, an mcp.json and a skills/ folder, which is close to what .agents/ already holds.

agents plugin export --name my-stack --plugin-version 1.0.0

dist/agent-plugin/
├── plugin.json      $schema, name, version, description
├── mcp.json         $schema, mcpServers
└── skills/          copied from .agents/skills

Export reads .agents/agents.json only, never local.json: what ships is the ${VAR} placeholder from the committed file, and the command prints which variables the package needs. ${PROJECT_ROOT} becomes the specification's ${PLUGIN_ROOT}.

Going the other way, agents plugin import ./some-plugin adds the package's servers under its plugin name (my-stack.docs) so nothing you already defined is replaced.

Context Budget

MCP servers cost context before an agent does any work: every tool definition is loaded up front.

agents mcp budget

MCP context budget:
  everything              13 tools  ~  1916 tokens
  filesystem              11 tools  ~  1240 tokens
  broken                 error: spawn broken-server ENOENT

Servers        3
Tools          24
Estimated      ~3156 tokens of context

The command speaks MCP 2026-07-28 directly over stdio and streamable HTTP, so the numbers come from the servers themselves. Servers built against the handshake revisions (2025-11-25 and earlier) are detected and handled the way the specification prescribes, so both eras work. Token counts are estimated from the size of the tool definitions, not measured by a model. Add --verbose for a per-tool breakdown, and --profile to measure what one profile would cost.

Servers whose config still contains an unresolved ${VAR} are skipped rather than started.

MCP Server Examples

# From a catalog URL
agents mcp add https://mcpservers.org/servers/context7-mcp

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

# HTTP server with a secret header
agents mcp add company-api --url "https://api.company.com/mcp" \
  --secret-header "Authorization=Bearer YOUR_API_TOKEN"

# Only for specific tools
agents mcp add ide-server --command ide-mcp --target cursor --target zed

A server definition supports timeout, connectTimeout, tools, disabledTools, oauth, headersHelper, bearerTokenEnvVar and envFile. Each is written only for the tools that document it, and the sync says when a field is dropped for a target that does not support it.

Values support ${VAR} and ${VAR:-default}, plus ${PROJECT_ROOT}.

Security

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

Secret-looking values are moved to local.json and replaced with ${PLACEHOLDER} in agents.json when a server is added.
agents doctor warns about literal secrets in committed config.
Env keys and header names are validated before they reach a config file or a shell.
agents plugin export never reads local.json.
A config this CLI does not gitignore keeps the ${VAR} placeholder from agents.json, whether the value would have come from local.json or from your shell. Amp, Zed and Kilo share a file with the tool's own settings, and .github/mcp.json is a file teams review; the sync lists which variables to export so those tools can resolve them. commit-generated mode holds secrets back from every generated config for the same reason.
A config this CLI rewrites keeps the permissions it had, so a file you restricted to 0600 stays that way.

Team Workflow

Lead sets up the project:

agents start
agents mcp add https://mcpservers.org/servers/context7-mcp
git add .agents/agents.json .agents/skills/ AGENTS.md && git commit -m "Add agents config"

In source-only mode that is everything the team needs: each clone runs agents sync and gets the tool configs locally. Switch syncMode to commit-generated if you would rather commit .mcp.json and the rest for people who do not install the CLI.

New member onboards:

git clone <repo> && cd <repo>
agents start        # keeps the committed config, writes local tool files

CI:

agents sync --check  # exits 2 when a tool config drifted from .agents/

FAQ

Does this replace AGENTS.md?

No. AGENTS.md stays the instruction file every tool reads. This CLI handles the machine-readable side (MCP servers, skills, per-tool config) and generates the minimal root CLAUDE.md wrapper Claude Code needs, since Claude Code does not read AGENTS.md.

Why does Claude Code use .mcp.json now?

Project scope is the location Anthropic documents for teams: it lives in the repository, so everyone working on it gets the same servers, and in `commit-generated` mode it is reviewed like any other file. Before 0.9.0 the CLI registered servers in the machine-local ~/.claude.json, which nobody else could see. Set integrations.options.claudeScope to "local" for the old behaviour; projects upgrading from schema 3 keep it automatically.

Can I use this with only one tool?

Yes. Secret splitting, drift checks, plugin export and the context budget are useful with a single tool.

What happens during agents sync?

It reads .agents/, merges local.json, resolves placeholders, applies the active profile, renders each tool's format and writes files atomically. Files shared with a tool's own settings (Amp, Zed, Kilo, Gemini, OpenCode, Goose) are merged, so settings the CLI does not own survive. Runs are idempotent.

Can I target an MCP server to specific tools only?

Yes, with "targets" in the definition or --target on agents mcp add. The exception is .mcp.json, which Claude Code and Copilot CLI both read: a server in that file is visible to both, and the sync warns instead of implying otherwise.

What does agents doctor check?

Missing or invalid config, literal secrets in committed files, unresolved env vars, drift in generated files, Codex project trust, a global Codex config that cannot be parsed, deprecated sse transports, skill frontmatter against the Agent Skills specification, and the state of skill bridges.

How do I upgrade from 0.8.x?

Run any command. .agents/agents.json migrates from schema 3 to 4 automatically and the previous file is kept as agents.json.v3.bak. Nothing else is required.

Documentation

docs/agents-system.md — how sync, skills and generated files work
docs/EXAMPLES.md — project setups
CONTRIBUTING.md — development workflow
CHANGELOG.md — release history

License

Apache 2.0. See LICENSE and NOTICE.

Name		Name	Last commit message	Last commit date
.agents		.agents
.github/workflows		.github/workflows
bin		bin
docs		docs
fixtures/basic/.agents/mcp		fixtures/basic/.agents/mcp
src		src
templates/agents		templates/agents
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

agents

The Problem

Quick Start

Supported Integrations

Project Layout

Command Overview

Setup & Sync

Diagnostics

MCP Servers

Profiles

Plugins

Skills & Integrations

Global Mode

Agent Plugins

Context Budget

MCP Server Examples

Security

Team Workflow

FAQ

Documentation

License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

agents

The Problem

Quick Start

Supported Integrations

Project Layout

Command Overview

Setup & Sync

Diagnostics

MCP Servers

Profiles

Plugins

Skills & Integrations

Global Mode

Agent Plugins

Context Budget

MCP Server Examples

Security

Team Workflow

FAQ

Documentation

License

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages