amtiyo/agents

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:

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 
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 and materializes a physical flat copy at .gemini/skills when Antigravity is enabled. Nested source skills remain under .agents/skills; duplicate skill names are rejected for the flat bridge. Global Antigravity editor/CLI profile files are left user-owned.

---

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/                  │  Gemini symlink; physical flat copy for Antigravity
├── .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

Diagnostics

MCP Server Management

Integrations

---

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              │  (flat copy for Antigravity)
│                                  .junie/skills               │
│                                  .windsurf/skills            │
└──────────────────────────────────────────────────────────────┘

1. Load — reads .agents/agents.json + merges secrets from .agents/local.json
2. Resolve — expands ${PROJECT_ROOT}, ${ENV_VAR} placeholders, filters by enabled and requiredEnv
3. Route — sends each server to its target integrations (or all, if no targets specified)
4. Generate — renders tool-specific config formats (TOML for Codex, JSON for others)
5. 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
6. Bridge skills — creates symlinks from tool directories to .agents/skills/ where needed; Antigravity receives a physical flat copy at .gemini/skills so nested skills are discoverable

---

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

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

---

Community