The missing toolchain for CLI coding agents. Pin versions per project. Share config across Claude Code, Codex, Gemini CLI, and Cursor. Stop setting up the same MCP server three times.
demo.mp4
npm install -g @swarmify/agents-cli
# or
bun install -g @swarmify/agents-cliSource: github.com/swarmify/agents-cli
Also available as ag -- all commands work with both agents and ag.
- Pin versions per project
- One config, every agent
- Run any agent
- Sessions across agents
- Run open models through Claude Code
- Teams
- Secrets
- Routines
- PTY
- Portable setup
- Private skills
- Compatibility
- FAQ
# This project needs claude@2.0.65 -- newer versions changed tool calling.
agents use claude@2.0.65 -p
# The monorepo uses codex@0.116.0 across the team.
agents use codex@0.116.0 -pLike .nvmrc for Node. A shim reads agents.yaml from the project root and routes claude / codex / gemini to the right version automatically. Each version gets its own isolated home -- switching backs up config and re-syncs resources.
agents add claude@2.0.65 # Install a specific version
agents add codex@latest # Install latest
agents view # See everything installed# Set up the Notion MCP server once.
agents install mcp:com.notion/mcp
# It's now registered with Claude Code, Codex, Gemini CLI, and Cursor.
agents mcp listSkills, slash commands, rules, hooks, and permissions work the same way -- install once in ~/.agents/, synced to every agent's native format automatically.
agents skills add gh:yourteam/python-expert # Knowledge pack -> all agents
agents commands add gh:yourteam/commands # Slash commands -> all agents
agents rules add gh:team/rules # AGENTS.md -> CLAUDE.md, GEMINI.md, .cursorrules
agents permissions add ./perms # Permissions -> auto-converted per agentWrite one AGENTS.md. It becomes CLAUDE.md for Claude Code, GEMINI.md for Gemini CLI, .cursorrules for Cursor.
agents run claude "Find all auth vulnerabilities in src/"
agents run codex "Fix the issues Claude found"
agents run gemini "Write tests for the fixed code"Each resolves to the project-pinned version with skills, MCP servers, and permissions already synced.
# Claude Code hits a rate limit -> Codex picks up automatically. Same project, same config.
agents run claude "refactor auth module" --mode edit --fallback codex,gemini# Picks the signed-in account you haven't used recently.
agents run claude "summarize recent commits" --rotate--rotate cycles across installed versions of the same agent -- useful when you have multiple accounts and want to spread usage instead of burning through one.
agents run claude "Review PRs merged this week, summarize risks" \
| agents run codex "Write regression tests for the top 3 risks"Supports plan (read-only) and edit modes, effort levels, JSON output for scripting, and timeout limits.
# Typed event stream instead of raw stdout. Same command, any supported agent.
agents run claude "review this diff" --acp --json--acp routes through the Agent Client Protocol so you get a unified event stream -- agent_message_chunk, tool_call, plan_update, stop_reason -- instead of writing a parser per CLI. File writes and shell commands flow through agents-cli, which means --mode plan becomes a real sandbox: the write RPC is denied, not just unused.
Works today with claude, codex, gemini, cursor, opencode, openclaw. Other harnesses keep running on the direct-exec path.
# Where was that auth conversation? Search Claude Code, Codex, Gemini CLI, OpenCode at once.
agents sessions "auth middleware"
# Filter by agent, project, or time window
agents sessions --agent codex --since 7d
agents sessions --project my-app
# Read a full conversation
agents sessions a1b2c3d4 --markdown
# Just the last 3 turns, user messages only
agents sessions a1b2c3d4 --last 3 --include userInteractive picker when you're in a terminal. Structured output (--json, --markdown, filtered by role or turn count) when piped.
Backed by a SQLite + FTS5 index at ~/.agents/sessions/sessions.db with incremental scanning -- warm reads in ~100ms. External tools can consume --json output as a programmatic observability layer; see docs/05-sessions.md for the schema and docs/06-observability.md for the consumption patterns.
# Kimi K2.5 responding inside Claude Code's UI, tools, and skills.
# No proxy server. No LiteLLM. One OpenRouter key, stored in Keychain.
agents profiles add kimi
agents run kimi "refactor this file"Built-in presets (all via OpenRouter, one shared key):
| Preset | Model | Notes |
|---|---|---|
kimi |
Kimi K2.5 | #1 HumanEval. Reasoning -- interactive only. |
minimax |
MiniMax M2.5 | #1 SWE-bench Verified. Reasoning. |
glm |
GLM 5 | #1 Chatbot Arena (open-weight). |
qwen |
Qwen3 Coder Next | Latest coding Qwen. Print-safe. |
deepseek |
DeepSeek Chat V3 | Latest non-reasoning. Print-safe. |
A profile swaps the model while keeping Claude Code as the agent runtime -- same UI, slash commands, skills, MCP tools. Under the hood: ANTHROPIC_BASE_URL + ANTHROPIC_MODEL, auth from Keychain at spawn time.
Custom endpoints (Ollama, vLLM) work too -- drop a YAML in ~/.agents/profiles/:
name: local-qwen
host: { agent: claude }
env:
ANTHROPIC_BASE_URL: https://ollama.internal
ANTHROPIC_MODEL: qwen3.6:35b
auth:
envVar: ANTHROPIC_AUTH_TOKEN
keychainItem: agents-cli.ollama.tokenProfile YAML has no secrets -- safe to agents push to a shared repo. agents profiles presets lists the full catalog.
agents teams create auth-feature
# Research first, then implement, then test.
agents teams add auth-feature claude "Research auth libraries" --name researcher
agents teams add auth-feature codex "Draft the migration" --name migrator --after researcher
agents teams add auth-feature claude "Write tests for the new code" --name tester --after migrator
agents teams start auth-feature # Fires teammates whose deps are done
agents teams status auth-feature # Who's working, what they changed, what they saidTeammates run detached -- close your terminal, they keep working. Check in with teams status, read full output with teams logs <name>, clean up with teams disband.
Team state is observable via agents teams list --json / agents teams status --json. External tools join it with sessions --json (teammates get isTeamOrigin: true) and cloud list --json (for --cloud teammates) to build a unified fleet view. See docs/06-observability.md.
# API keys in Keychain, not in .env files.
agents secrets create prod-stripe
agents secrets add prod-stripe STRIPE_SECRET_KEY # Prompts, stores in Keychain
agents secrets add prod-stripe TEST_CARD --value "4242..."
# Injected at run time. The YAML on disk has only refs.
agents run claude "charge a test card" --secrets prod-stripe
Merge order: profile env < --secrets < --env K=V. A missing keychain item aborts before the child starts.
# Claude Code reviews PRs every weekday at 9 AM. Scheduler auto-starts.
agents routines add daily-digest \
--schedule "0 9 * * 1-5" \
--agent claude \
--prompt "Review yesterday's PRs and summarize key changes"
agents routines list # All jobs + next run times
agents routines run daily-digest # Test it now, ignore the schedule
agents routines logs daily-digest # Check last executionJobs run sandboxed -- agents only see directories and tools you explicitly allow.
# Give agents a real terminal for REPLs, TUIs, interactive programs.
SID=$(agents pty start)
agents pty exec $SID "python3"
agents pty screen $SID # Clean text, no ANSI -- what a human sees
agents pty write $SID "print('hello')\n"
agents pty stop $SIDA sidecar server holds sessions alive between CLI calls. screen renders via xterm-headless. Sessions auto-clean after 30 minutes idle.
# New machine? One command.
agents pull
# Installs CLIs, registers MCP servers, syncs skills/commands/rules/hooks,
# sets up shims, configures defaults. Done.
agents push # Snapshot your config to gitKeep work or personal skills in a separate repo — public ones in ~/.agents/, private ones in an extra repo that merges in at sync time.
# Add a private repo for work-only skills
agents repo add gh:yourname/.agents-work
# Add with a custom alias
agents repo add git@github.com:acme/team-skills.git --as acme
agents repo list # Primary + every registered extra
agents repo pull # Pull updates for all enabled extras
agents repo disable acme # Stop merging without deleting
agents repo remove acme # Unregister and delete the cloneExtras clone into ~/.agents/.repos/<alias>/ and ship the same layout as the primary (skills/, commands/, hooks/, memory/). Their contents merge into agent version homes after the primary's — so ~/.agents/ always wins on name collisions. agents skills list shows which repo each skill came from.
| Agent | Versions | MCP | Commands | Skills | Rules | Hooks | Plugins | Permissions | Routines | Teams |
|---|---|---|---|---|---|---|---|---|---|---|
| Claude Code | yes | yes | yes | yes | CLAUDE.md | yes | yes | yes | yes | yes |
| Codex CLI | yes | yes | yes | yes | AGENTS.md | yes (>= 0.116.0) | -- | yes | yes | yes |
| Gemini CLI | yes | yes | yes | yes | GEMINI.md | yes (>= 0.26.0) | -- | -- | yes | yes |
| OpenClaw | yes | yes | -- | yes | workspace/AGENTS.md | yes | yes | -- | -- | -- |
| Cursor | yes | yes | yes | yes | .cursorrules | -- | -- | -- | -- | yes |
| OpenCode | yes | yes | yes | yes | AGENTS.md | -- | -- | yes | -- | yes |
| Copilot | yes | yes | yes | yes | AGENTS.md | -- | -- | -- | -- | -- |
| Amp | yes | yes | yes | yes | AGENTS.md | -- | -- | -- | -- | -- |
| Kiro | yes | yes | yes | yes | AGENTS.md | -- | -- | -- | -- | -- |
| Goose | yes | yes | -- | -- | AGENTS.md | -- | -- | -- | -- | -- |
| Roo Code | yes | yes | yes | yes | AGENTS.md | -- | -- | -- | -- | -- |
Hooks columns marked yes (>= X.Y.Z) are version-gated: agents hooks add skips with a clear message when the installed binary is older than the listed version, instead of writing config the older binary would silently ignore. OpenCode's plugin-based hook system is on the roadmap; the entry is -- until a writer ships.
Claude Code, Codex CLI, and Gemini CLI each have their own config format, MCP setup, version management, and skill system. If you use more than one, you maintain N copies of everything. agents gives you one interface, one config source, and one place to pin versions -- plus features the individual CLIs don't ship: cross-agent pipelines, shared teams, unified session search, and project-pinned versions like .nvmrc.
For version management, yes. agents-cli reads agents.yaml from the project root, walks up the directory tree, and routes to the correct binary per project. But it also manages agent-native resources (skills, MCP servers, commands, hooks, permissions) that language version managers don't touch.
No. API keys come from your shell environment or each agent CLI's existing auth. No telemetry, no phone-home. All state lives in ~/.agents/.
macOS and Linux. Windows via WSL works but isn't first-class yet.
The installer tries Bun first (faster), falls back to npm. Node 18+ required at runtime.
Yes -- agents run is non-interactive by default. --yes auto-accepts prompts, --json for structured output. Pass explicit names and IDs instead of relying on interactive pickers.
Agents are defined in src/lib/agents.ts -- each is a config object declaring commands dir, memory file, and capabilities. PRs welcome.
agents-cli is an open client maintained by Phoenix Labs. Rush is a separate product. No Rush account required, no upsell.
git clone https://github.com/swarmify/agents-cli
cd agents-cli
bun install && bun run build && bun testCommands in src/commands/, libraries in src/lib/, tests as *.test.ts under vitest. CLAUDE.md has the full style guide. docs/04-landscape.md covers the competitive landscape.
MIT -- see LICENSE.