The missing toolchain for CLI coding agents. Pin versions to escape regressions. Build hooks to control agent behavior, or skills to improve them. Then share your agent environment with your team, or clone it to any machine with one command.

https://github.com/user-attachments/assets/cf0b2248-6672-4458-8027-b88525572f3e

npm install -g @phnx-labs/agents-cli
# or
bun install -g @phnx-labs/agents-cli

Source: github.com/phnx-labs/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
• Browser
• Secrets
• Routines
• PTY
• Portable setup
• Private skills
• Security & Privacy
• Compatibility
• FAQ

Pin versions per project

# This project needs [email protected] -- newer versions changed tool calling.
agents use [email protected] -p

# The monorepo uses [email protected] across the team.
agents use [email protected] -p

This creates an agents.yaml at the project root:

# agents.yaml (commit this to your repo)
agents:
  claude: "2.0.65"
  codex: "0.116.0"

Think requirements.txt for CLI coding agents, on steroids. 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 [email protected]     # Install a specific version
agents add codex@latest       # Install latest
agents view                   # See everything installed

One config, every agent

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

Skills, 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 agent

Write one AGENTS.md. It becomes CLAUDE.md for Claude Code, GEMINI.md for Gemini CLI, .cursorrules for Cursor.

Run any agent

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.

Rate-limited? Keep working.

# 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

Multiple accounts? Spread the load.

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

Chain agents

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.

One protocol, every harness

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

Sessions across agents

When you run multiple agents, conversations scatter across tools. Session search brings them together.

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

Interactive 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-system/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.

Run open models through Claude Code (experimental)

Note: Profiles are experimental. Enable with agents beta profiles enable.

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

Profile YAML has no secrets -- safe to agents repo push to a shared repo. agents profiles presets lists the full catalog.

Teams

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 said

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

Browser

Give agents access to a real browser — no relay extension, no cloud service, no Playwright getting blocked.

# Create an isolated profile for automation
agents browser profiles create work --browser chrome

# Start a task, navigate, interact
agents browser start --profile work --task login-flow --url https://app.example.com
agents browser refs login-flow              # Get interactive element refs
agents browser click login-flow 42          # Click element ref 42
agents browser type login-flow 15 "hello"   # Type into element ref 15
agents browser screenshot login-flow        # Smart resizing, token-efficient
agents browser done login-flow              # Close task's tabs when finished

Why this works where Playwright fails

Playwright and Puppeteer spin up fresh browser instances with automation flags. Sites like LinkedIn, Google, and most finance apps detect and block them immediately.

agents browser launches your existing residential Chrome (or Brave, Edge, Chromium) on your machine via CDP. Same browser fingerprint, same IP, same everything. Sites can't detect automation because you're using the same browser you'd use manually.

Token-efficient automation

The CLI handles the mechanical work so agents don't burn tokens on low-level browser commands. Screenshots are automatically resized without excessive compression — agents process smaller images while keeping the detail they need to make decisions.

Profile isolation

Multiple agents can run browser tasks simultaneously without stepping on each other. Each profile gets its own user data directory, cookies, and state. One agent logs into your work Slack, another into your personal email — no conflicts, no shared state.

agents browser profiles create work-slack --browser chrome
agents browser profiles create personal-gmail --browser chrome
# Two agents, two profiles, no interference

Safe credential access

Attach a secrets bundle to a profile. The agent can log in without credentials in plaintext, and every secret access is recorded in the session log.

agents browser profiles create bank --browser chrome --secrets bank-creds

Electron apps

Control Electron apps (Slack, Discord, VS Code, your own app) with custom binaries:

agents browser profiles create slack \
  --browser custom \
  --binary "/Applications/Slack.app/Contents/MacOS/Slack" \
  --electron

Remote browsers

Connect to browsers running anywhere — local, SSH tunnels, or cloud services:

# Local CDP (discovers WebSocket URL automatically)
agents browser profiles create local-debug \
  --browser chrome \
  --endpoint "http://localhost:9222"

# SSH tunnel to a remote machine
agents browser profiles create staging \
  --browser chrome \
  --endpoint "ssh://[email protected]?port=9222"

# Cloud browser services (BrowserBase, Steel, etc.)
agents browser profiles create cloud \
  --browser chrome \
  --endpoint "wss://connect.browserbase.com?apiKey=..."

Secrets

# 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. Bundle definitions live in the Keychain, not on disk.
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.

Cross-machine sync via iCloud Keychain

Pass --icloud-sync when creating a bundle and both the bundle definition and its values are written to the iCloud-synced keychain. Sign into the same iCloud account on another Mac (with iCloud Keychain enabled) and the bundle appears there within seconds — no copy-paste, no .env files emailed to yourself, no shared secret stores.

# On laptop:
agents secrets create npm-tokens --icloud-sync
agents secrets add npm-tokens NPM_TOKEN          # value lives in iCloud Keychain

# On another Mac (same iCloud account):
agents secrets list                              # npm-tokens is already there;
agents run claude "..." --secrets npm-tokens     # injects NPM_TOKEN automatically

Under the hood, --icloud-sync routes writes through a notarized helper app (AgentsKeychain.app) that holds the entitlement macOS requires for kSecAttrSynchronizable. Bundles without --icloud-sync stay device-local.

Bundle definitions sync via iCloud Keychain too — no agents repo push needed for secrets, no recreate step on each Mac. Nothing about secrets ever lives in plaintext on disk.

Per-secret metadata and rotation

Tag each secret with --type, --expires, and --note so the bundle is self-documenting. --expires is always future-dated (YYYY-MM-DD); past or same-day values are rejected. Use agents secrets rotate <bundle> <key> to refresh a credential — add only creates new keys, rotate replaces the value and preserves metadata unless overridden.

agents secrets add prod STRIPE_API_KEY --type api-key --expires 2027-01-15 --note "Live key, owner: payments-team"
agents secrets rotate prod STRIPE_API_KEY --note "rotated after suspected leak"
agents secrets list   # EXPIRING column flags secrets due in the next 30 days

Routines

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

Jobs run sandboxed -- agents only see directories and tools you explicitly allow.

PTY

# 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 $SID

A sidecar server holds sessions alive between CLI calls. screen renders via xterm-headless. Sessions auto-clean after 30 minutes idle.

Portable setup

# New machine? One command.
agents init

# Installs CLIs, registers MCP servers, syncs skills/commands/rules/hooks,
# sets up shims, configures defaults. Done.

agents repo push     # Snapshot your config to git

How config is layered

Two repos with the same shape, different roles:

| Repo | Role | Owner | |---|---|---| | ~/.agents-system/ | System repo — core/built-in skills, commands, hooks, rules, MCP configs, permissions, and profiles that ship with agents-cli. The defaults every install gets. | Maintained upstream at phnx-labs/.agents-system | | ~/.agents/ | User repo — your personal additions and overrides. This is what agents repo push/pull syncs. | You |

Version pinning: agents.yaml at project root pins which agent version to use (like .nvmrc for Node).

Resource resolution: When syncing resources (commands, skills, rules, hooks, MCP, permissions), the order is project > user > system. A .agents/ directory at project root wins, then ~/.agents/, then ~/.agents-system/. Same-named resources higher in the chain override lower ones; everything else unions in.

See docs/00-concepts.md for the full mental model: DotAgents repos, resource kinds, and how resolution works end-to-end.

Private skills

Keep 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 [email protected]: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 clone

Extras clone into ~/.agents-system/.repos/<alias>/ and ship the same layout as the primary (skills/, commands/, hooks/, rules/). 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.

Security & Privacy

Everything stays on your machine. No telemetry, no cloud sync (unless you opt into iCloud Keychain for secrets), no phone-home. Here's exactly what agents-cli stores locally and why.

Event log

Every agent run, version install, browser launch, and secrets access is logged to ~/.agents/logs/events-YYYY-MM-DD.jsonl. This gives you a complete record of what agents did on your machine.

# What gets logged (example event):
{
  "ts": "2026-05-09T10:23:45Z",
  "event": "agent.run.end",
  "agent": "claude",
  "version": "2.1.121",
  "prompt": "Fix the auth bug in...",  # truncated to 200 chars
  "durationMs": 45230,
  "exitCode": 0,
  "hostname": "your-mac",
  "platform": "darwin"
}

What's logged: Operation type, agent, version, timing, truncated prompts (first 200 chars), exit codes, errors. What's NOT logged: Full prompts, outputs, file contents, secret values (only bundle names).

Permissions: Logs directory is 0700 (owner-only), files are 0600. Only you can read them.

Retention: 30 days by default, then auto-pruned.

Opt out: Set AGENTS_DISABLE_EVENT_LOG=1 in your shell to disable completely.

Session search

Conversations with Claude, Codex, Gemini, and other agents scatter across their native storage. Session search indexes them locally so you can find any conversation:

agents sessions "auth middleware"     # Full-text search across all agents
agents sessions --agent claude --since 7d

The index lives at ~/.agents/sessions/sessions.db (SQLite + FTS5). Nothing leaves your machine. See Sessions for full usage.

Secrets

API keys and credentials are stored in macOS Keychain, never in plaintext files. Bundle definitions also live in Keychain.

agents secrets create my-keys
agents secrets add my-keys API_KEY    # Prompts for value, stores in Keychain

With --icloud-sync, secrets sync via iCloud Keychain to your other Macs. Without it, they stay device-local. See Secrets for full usage.

Summary

| Data | Location | Who can read | Opt out | |------|----------|--------------|---------| | Event log | ~/.agents/logs/ | You only (0600) | AGENTS_DISABLE_EVENT_LOG=1 | | Session index | ~/.agents/sessions/ | You only | Delete the directory | | Secrets | macOS Keychain | You + apps you authorize | Don't use agents secrets | | Config | ~/.agents/ | You only | N/A |

Compatibility

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

Codex command sync is version-aware: Codex 0.116.x and older receive slash commands in .codex/prompts/; Codex 0.117.0+ receives those commands as generated skills so they can be invoked with $name.

FAQ

Why use agents instead of claude / codex / gemini directly?

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.

Is it free?

Yes. This developer tool is entirely free because we believe developers should have the best tools — fast and robust — so they can create the best products for their users.

Is this like nvm / mise / asdf for AI agents?

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.

How does version switching actually work?

Same approach as nvm, pyenv, and rbenv — battle-tested by millions of developers. When you install a version, we set up a shim script that resolves the version from agents.yaml and runs the right binary. Each version has an isolated config directory. No manual setup required.

How do I share my agent setup with my team?

Add a .agents/ directory at your project root with your skills, hooks, rules, and commands. Resources merge automatically: project > user (~/.agents/) > system (~/.agents-system/). Commit it with your repo and teammates get the same agent environment.

Do I need to write separate rules for each agent (CLAUDE.md, GEMINI.md, etc.)?

No. Write one AGENTS.md — it's the canonical source. We automatically sync it to each agent's expected location (CLAUDE.md for Claude Code, GEMINI.md for Gemini CLI, .cursorrules for Cursor). Same content, zero duplication.

Do agents use API keys or subscriptions?

Your choice. We hand off to the original CLI process — use your existing subscription or API key. This is intentional: subscription pricing is usually cheaper than API token pricing for individual users. Configure each agent however you want.

Does it store my API keys or send telemetry?

No telemetry, no phone-home. Everything stays local. API keys come from your shell environment or each agent CLI's existing auth.

For full transparency: agents-cli keeps a local event log at ~/.agents/logs/ so you can see exactly what agents did on your machine. Logs are owner-readable only (0600) and auto-prune after 30 days. Set AGENTS_DISABLE_EVENT_LOG=1 to disable. See Security & Privacy for details.

Which platforms?

macOS and Linux. Windows via WSL works but isn't first-class yet.

macOS-only features: Keychain-based secrets (agents secrets, agents profiles login) require macOS. The --icloud-sync flag on bundles requires macOS + iCloud Keychain enabled. On Linux, use environment variables or .env files for API keys. Native Linux credential store support is planned.

Do I need Node.js?

The installer tries Bun first (faster), falls back to npm. Node 18+ required at runtime.

Can I use it in CI?

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.

What happens to my config when I switch versions?

Each version has its own isolated config directory. Switching just repoints a symlink — your per-version config stays untouched. On first migration (if you had a real ~/.claude/ directory before using agents-cli), that gets backed up once to ~/.agents-system/backups/.

Does session search use RAG or semantic search?

No — it's a SQLite + FTS5 full-text index. Fast, flexible, and robust. Agents can query sessions programmatically. Most commands support --json output for scripting with jq.

How do I use custom or local models?

Profiles (experimental — enable with agents beta profiles enable). Works with LiteLLM Proxy, Ollama, or any OpenAI-compatible endpoint. Drop a YAML in ~/.agents/profiles/ pointing to your endpoint.

Can I add support for a new agent?

Agents are defined in src/lib/agents.ts -- each is a config object declaring commands dir, rules file, and capabilities. PRs welcome.

What's the relationship to Phoenix Labs / Rush?

agents-cli is an open client maintained by Phoenix Labs. Rush is a separate product. No Rush account required, no upsell.

Contributing

git clone https://github.com/phnx-labs/agents-cli
cd agents-cli
bun install && bun run build && bun test

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

License

MIT -- see LICENSE.