Skip to content
Back to search

agents

One .agents source of truth to sync MCP servers, skills, and instructions across Codex, Claude Code, Gemini CLI, Cursor, Copilot, and Antigravity.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/amtiyo--agents/badge.svg)](/listings/amtiyo--agents)

HTML

<a href="/listings/amtiyo--agents"><img src="/api/listings/amtiyo--agents/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 373 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <h1 align="center">agents</h1>
  2. <p align="center"><strong>One config to rule them all.</strong><br/>Practical standard layer for multi-LLM development.</p>
  3. <p align="center">
  4. <a href="https://www.npmjs.com/package/@agents-dev/cli"><img src="https://img.shields.io/npm/v/@agents-dev/cli?style=for-the-badge&logo=npm&logoColor=white&labelColor=0f172a&color=e11d48" alt="npm version"></a>
  5. <a href="https://www.npmjs.com/package/@agents-dev/cli"><img src="https://img.shields.io/npm/dt/@agents-dev/cli?style=for-the-badge&logo=npm&logoColor=white&labelColor=0f172a&color=2563eb" alt="downloads"></a>
  6. <a href="https://www.npmjs.com/package/@agents-dev/cli"><img src="https://img.shields.io/node/v/@agents-dev/cli?style=for-the-badge&logo=node.js&logoColor=white&labelColor=0f172a&color=10b981" alt="node version"></a>
  7. <a href="https://www.apache.org/licenses/LICENSE-2.0"><img src="https://img.shields.io/badge/license-Apache%202.0-334155?style=for-the-badge&labelColor=0f172a" alt="license"></a>
  8. </p>
  9. <p align="center">
  10. <a href="#quick-start">Quick Start</a> ·
  11. <a href="#supported-integrations">Integrations</a> ·
  12. <a href="#command-overview">Commands</a> ·
  13. <a href="#agent-plugins">Plugins</a> ·
  14. <a href="#faq">FAQ</a>
  15. </p>
  16. <p align="center">
  17. <img src="docs/screenshot.jpg" alt="agents start" width="860">
  18. </p>
  19. ---
  20. ## The Problem
  21. 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:
  22. | Format | Tools |
  23. |:--|:--|
  24. | TOML, `mcp_servers` tables | Codex (`.codex/config.toml`), Grok Build (`.grok/config.toml`) |
  25. | 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`) |
  26. | JSON, another key | Copilot VS Code (`servers`), OpenCode and Kilo (`mcp`), Amp (`amp.mcpServers`), Zed (`context_servers`) |
  27. | YAML | Goose (`extensions` in `~/.config/goose/config.yaml`) |
  28. Add a server by hand and you write it 18 times, then watch the copies drift apart.
  29. `agents` keeps one source of truth in `.agents/` and materializes it for every tool you enable.
  30. ---
  31. ## Quick Start
  32. ```bash
  33. # 1. Install
  34. npm install -g @agents-dev/cli
  35. # 2. Interactive setup — picks integrations, adds MCP servers, syncs everything
  36. agents start
  37. # 3. Re-sync whenever config changes
  38. agents sync
  39. ```
  40. `.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.
  41. ---
  42. ## Supported Integrations
  43. 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.
  44. | Integration | `--llm` id | MCP config it writes | Skills | Verified |
  45. |:--|:--|:--|:--:|:--:|
  46. | Codex | `codex` | `.codex/config.toml` (managed block, project trust handled) | native | ✅ |
  47. | Claude Code | `claude` | `.mcp.json` project scope or CLI local/user scope, plus root `CLAUDE.md` wrapper | bridge | ✅ |
  48. | Claude Desktop | `claude_desktop` | global `claude_desktop_config.json`, stdio servers only | — | ✅ |
  49. | Gemini CLI | `gemini` | `.gemini/settings.json` | bridge | ✅ |
  50. | Cursor | `cursor` | `.cursor/mcp.json` + CLI enable | bridge | ✅ |
  51. | Copilot VS Code | `copilot_vscode` | `.vscode/mcp.json` | native | ✅ |
  52. | Copilot CLI | `copilot_cli` | `.mcp.json`, or `.github/mcp.json` | native | ✅ |
  53. | Antigravity | `antigravity` | `.agents/mcp_config.json` | flat copy | ✅ |
  54. | Devin Desktop (Windsurf) | `windsurf`, `devin_desktop` | global `~/.codeium/windsurf/mcp_config.json` | bridge | ✅ |
  55. | OpenCode | `opencode` | `opencode.json` (`mcp`, or `mcp.servers` for OpenCode 2) | native | ✅ |
  56. | Junie | `junie` | `.junie/mcp/mcp.json` | bridge | ✅ |
  57. | Grok Build | `grok` | `.grok/config.toml` (managed block, folder trust handled) | native | ✅ |
  58. | Amp | `amp` | `.amp/settings.json` (`amp.mcpServers`) | native | ✅ |
  59. | Factory Droid | `droid`, `factory` | `.factory/mcp.json` | native | ✅ |
  60. | Kilo | `kilo`, `kilocode` | `.kilo/kilo.jsonc` (`mcp`) | bridge | — |
  61. | Devin CLI | `devin` | `.devin/mcp_config.json` | native | ✅ |
  62. | Zed | `zed` | `.zed/settings.json` (`context_servers`) | native | — |
  63. | Goose | `goose` | `~/.config/goose/config.yaml` (`extensions`) | native | ✅ |
  64. **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.
  65. **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.
  66. **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.
  67. **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.
  68. ---
  69. ## Project Layout
  70. ```
  71. your-project/
  72. ├── AGENTS.md ← Canonical instructions for all tools
  73. ├── CLAUDE.md ← Generated Claude wrapper (`@AGENTS.md`)
  74. ├── .agents/
  75. │ ├── agents.json ← MCP servers, profiles, config (commit this)
  76. │ ├── local.json ← Secrets & overrides (gitignored)
  77. │ ├── mcp_config.json ← Generated Antigravity workspace MCP
  78. │ ├── skills/ ← Reusable workflow definitions
  79. │ │ └── my-skill/SKILL.md
  80. │ └── generated/ ← Auto-generated artifacts (gitignored)
  81. │
  82. │ ┌─── Generated by `agents sync` ───┐
  83. ├── .mcp.json │ Claude Code + Copilot CLI
  84. ├── .codex/config.toml │ Codex
  85. ├── .grok/config.toml │ Grok Build
  86. ├── .gemini/settings.json │ Gemini CLI
  87. ├── .cursor/mcp.json │ Cursor
  88. ├── .vscode/mcp.json │ Copilot VS Code
  89. ├── .amp/settings.json │ Amp
  90. ├── .factory/mcp.json │ Factory Droid
  91. ├── .kilo/kilo.jsonc │ Kilo
  92. ├── .devin/mcp_config.json │ Devin CLI
  93. ├── .zed/settings.json │ Zed
  94. ├── opencode.json │ OpenCode
  95. ├── .junie/mcp/mcp.json │ Junie
  96. └── .claude/skills → .agents/skills │ Skill bridges
  97. ```
  98. > **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.
  99. >
  100. > 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.
  101. ---
  102. ## Command Overview
  103. ### Setup & Sync
  104. | Command | Description |
  105. |:--------|:------------|
  106. | `agents start` | Interactive setup: integrations, MCP servers, skills, first sync |
  107. | `agents init` | Scaffold `.agents/` without the wizard |
  108. | `agents sync` | Regenerate and materialize all tool configs |
  109. | `agents sync --check` | Read-only drift check, exits `2` when out of sync |
  110. | `agents sync --profile ci` | Sync one profile without changing the active one |
  111. | `agents watch` | Auto-sync on `.agents/` changes |
  112. ### Diagnostics
  113. | Command | Description |
  114. |:--------|:------------|
  115. | `agents status` | Integrations, MCP servers, file states, live probes |
  116. | `agents doctor` | Validate configs and report problems |
  117. | `agents doctor --fix` | Apply the fixes it can make safely |
  118. | `agents update` | Check npm for a newer CLI |
  119. ### MCP Servers
  120. | Command | Description |
  121. |:--------|:------------|
  122. | `agents mcp add <name\|url>` | Add a server interactively or from a URL |
  123. | `agents mcp import --file config.json` | Bulk import from JSON/JSONC |
  124. | `agents mcp list` | List configured servers |
  125. | `agents mcp remove <name>` | Remove a server |
  126. | `agents mcp test [--runtime]` | Validate definitions, optionally through tool CLIs |
  127. | `agents mcp budget` | Connect to each server and measure its context cost |
  128. ### Profiles
  129. | Command | Description |
  130. |:--------|:------------|
  131. | `agents profile set ci --server docs --server git` | Create or replace a profile |
  132. | `agents profile use ci` | Activate a profile and sync |
  133. | `agents profile use` | Clear the profile, back to every server |
  134. | `agents profile list` | Show profiles and the active one |
  135. | `agents profile remove ci` | Delete a profile |
  136. ### Plugins
  137. | Command | Description |
  138. |:--------|:------------|
  139. | `agents plugin export --name my-stack` | Build an Agent Plugins v1 package from `.agents` |
  140. | `agents plugin validate <dir>` | Check a package against the specification |
  141. | `agents plugin import <dir>` | Add a package's servers and skills to this project |
  142. ### Skills & Integrations
  143. | Command | Description |
  144. |:--------|:------------|
  145. | `agents skills list` | List skills found under `.agents/skills/` |
  146. | `agents connect --llm cursor,grok` | Enable integrations |
  147. | `agents disconnect --llm codex` | Disable integrations |
  148. | `agents reset` | Remove generated files, keep `.agents/` |
  149. | `agents reset --hard` | Full cleanup |
  150. ### Global Mode
  151. Run any command with `--global` (or `-g`, or from `$HOME`) to manage MCP servers and skills machine-wide from `~/.agents/agents.json`:
  152. ```bash
  153. agents init -g
  154. agents connect -g --llm opencode,codex,grok
  155. agents sync -g
  156. ```
  157. Tools that only have a user-level config (Claude Desktop, Devin Desktop, Goose) are written there in both modes.
  158. ---
  159. ## Agent Plugins
  160. [Agent Plugins 1.0.0](https://agent-plugins.org/specification) 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.
  161. ```bash
  162. agents plugin export --name my-stack --plugin-version 1.0.0
  163. ```
  164. ```
  165. dist/agent-plugin/
  166. ├── plugin.json $schema, name, version, description
  167. ├── mcp.json $schema, mcpServers
  168. └── skills/ copied from .agents/skills
  169. ```
  170. 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}`.
  171. 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.
  172. ---
  173. ## Context Budget
  174. MCP servers cost context before an agent does any work: every tool definition is loaded up front.
  175. ```bash
  176. agents mcp budget
  177. ```
  178. ```
  179. MCP context budget:
  180. everything 13 tools ~ 1916 tokens
  181. filesystem 11 tools ~ 1240 tokens
  182. broken error: spawn broken-server ENOENT
  183. Servers 3
  184. Tools 24
  185. Estimated ~3156 tokens of context
  186. ```
  187. 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.
  188. Servers whose config still contains an unresolved `${VAR}` are skipped rather than started.
  189. ---
  190. ## MCP Server Examples
  191. ```bash
  192. # From a catalog URL
  193. agents mcp add https://mcpservers.org/servers/context7-mcp
  194. # stdio server
  195. agents mcp add my-server --command npx --arg @my-org/mcp-server --arg /path/to/project
  196. # HTTP server with a secret header
  197. agents mcp add company-api --url "https://api.company.com/mcp" \
  198. --secret-header "Authorization=Bearer YOUR_API_TOKEN"
  199. # Only for specific tools
  200. agents mcp add ide-server --command ide-mcp --target cursor --target zed
  201. ```
  202. 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.
  203. Values support `${VAR}` and `${VAR:-default}`, plus `${PROJECT_ROOT}`.
  204. ---
  205. ## Security
  206. | | What | Where |
  207. |:--|:-----|:------|
  208. | 🔓 | Server definitions, team config | `.agents/agents.json` — **committed** |
  209. | 🔒 | API keys, tokens, secrets | `.agents/local.json` — **gitignored** |
  210. - Secret-looking values are moved to `local.json` and replaced with `${PLACEHOLDER}` in `agents.json` when a server is added.
  211. - `agents doctor` warns about literal secrets in committed config.
  212. - Env keys and header names are validated before they reach a config file or a shell.
  213. - `agents plugin export` never reads `local.json`.
  214. - 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.
  215. - A config this CLI rewrites keeps the permissions it had, so a file you restricted to `0600` stays that way.
  216. ---
  217. ## Team Workflow
  218. **Lead sets up the project:**
  219. ```bash
  220. agents start
  221. agents mcp add https://mcpservers.org/servers/context7-mcp
  222. git add .agents/agents.json .agents/skills/ AGENTS.md && git commit -m "Add agents config"
  223. ```
  224. In `source-only` mode that is everything the team needs: each clone runs `agents sync` and
  225. gets the tool configs locally. Switch `syncMode` to `commit-generated` if you would rather
  226. commit `.mcp.json` and the rest for people who do not install the CLI.
  227. **New member onboards:**
  228. ```bash
  229. git clone <repo> && cd <repo>
  230. agents start # keeps the committed config, writes local tool files
  231. ```
  232. **CI:**
  233. ```bash
  234. agents sync --check # exits 2 when a tool config drifted from .agents/
  235. ```
  236. ---
  237. ## FAQ
  238. <details>
  239. <summary><b>Does this replace AGENTS.md?</b></summary>
  240. <br/>
  241. No. <code>AGENTS.md</code> 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 <code>CLAUDE.md</code> wrapper Claude Code needs, since Claude Code does not read <code>AGENTS.md</code>.
  242. </details>
  243. <details>
  244. <summary><b>Why does Claude Code use <code>.mcp.json</code> now?</b></summary>
  245. <br/>
  246. 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 <code>~/.claude.json</code>, which nobody else could see. Set <code>integrations.options.claudeScope</code> to <code>"local"</code> for the old behaviour; projects upgrading from schema 3 keep it automatically. For servers available in every project, set it to <code>"user"</code> (<code>"global"</code> is an alias) and run <code>agents sync -g</code>. New home-directory installs (<code>agents init -g</code> or <code>agents start -g</code>) default to user scope; normal repositories default to project scope. Existing explicit choices are preserved. See [Claude MCP scopes](docs/agents-system.md#claude-mcp-scopes) for migration and cleanup.
  247. </details>
  248. <details>
  249. <summary><b>Can I use this with only one tool?</b></summary>
  250. <br/>
  251. Yes. Secret splitting, drift checks, plugin export and the context budget are useful with a single tool.
  252. </details>
  253. <details>
  254. <summary><b>What happens during <code>agents sync</code>?</b></summary>
  255. <br/>
  256. It reads <code>.agents/</code>, merges <code>local.json</code>, 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. OpenCode gets the <code>mcp.&lt;name&gt;</code> shape that every OpenCode version reads, or the OpenCode 2 <code>mcp.servers</code> shape once the file already has <code>mcp.servers</code> or a server uses an option only OpenCode 2 has; see <a href="docs/EXAMPLES.md#opencode-mcp-options">OpenCode options</a>.
  257. </details>
  258. <details>
  259. <summary><b>Can I target an MCP server to specific tools only?</b></summary>
  260. <br/>
  261. Yes, with <code>"targets"</code> in the definition or <code>--target</code> on <code>agents mcp add</code>. The exception is <code>.mcp.json</code>, 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.
  262. </details>
  263. <details>
  264. <summary><b>What does <code>agents doctor</code> check?</b></summary>
  265. <br/>
  266. 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 <code>sse</code> transports, skill frontmatter against the Agent Skills specification, and the state of skill bridges.
  267. </details>
  268. <details>
  269. <summary><b>How do I upgrade from 0.8.x?</b></summary>
  270. <br/>
  271. Run any command. <code>.agents/agents.json</code> migrates from schema 3 to 4 automatically and the previous file is kept as <code>agents.json.v3.bak</code>. Nothing else is required.
  272. </details>
  273. ---
  274. ## Documentation
  275. - [`docs/agents-system.md`](docs/agents-system.md) — how sync, skills and generated files work
  276. - [`docs/EXAMPLES.md`](docs/EXAMPLES.md) — project setups
  277. - [`CONTRIBUTING.md`](CONTRIBUTING.md) — development workflow
  278. - [`CHANGELOG.md`](CHANGELOG.md) — release history
  279. ## License
  280. Apache 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.