@phnx-labs/agents-cli 1.12.0 → 1.14.2

package/README.md

@@ -1,455 +1,466 @@
-# agents
-
-[![npm version](https://img.shields.io/npm/v/@phnx-labs/agents-cli.svg?style=flat-square)](https://www.npmjs.com/package/@phnx-labs/agents-cli)
-[![license](https://img.shields.io/npm/l/@phnx-labs/agents-cli.svg?style=flat-square)](./LICENSE)
-[![downloads](https://img.shields.io/npm/dm/@phnx-labs/agents-cli.svg?style=flat-square)](https://www.npmjs.com/package/@phnx-labs/agents-cli)
-[![homepage](https://img.shields.io/badge/homepage-agents--cli.sh-blue?style=flat-square)](https://agents-cli.sh)
-
-**The open client for AI coding agents.** Run Claude, Codex, Gemini, Cursor — same interface, on your machine.
-
-Pin versions per project. Install skills, MCP servers, and slash commands once — every agent gets them. Chain agents in pipelines. Put agents on a team to work a shared task in parallel.
+<p align="center">
+  <img src="assets/logo.png" alt="agents" width="120" />
+</p>
+
+<h1 align="center">agents</h1>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@phnx-labs/agents-cli"><img src="https://img.shields.io/npm/v/@phnx-labs/agents-cli.svg?style=flat-square" alt="npm version" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/@phnx-labs/agents-cli.svg?style=flat-square" alt="license" /></a>
+  <a href="https://www.npmjs.com/package/@phnx-labs/agents-cli"><img src="https://img.shields.io/npm/dm/@phnx-labs/agents-cli.svg?style=flat-square" alt="downloads" /></a>
+  <a href="https://github.com/phnx-labs/agents-cli"><img src="https://img.shields.io/badge/github-phnx--labs%2Fagents--cli-blue?style=flat-square" alt="github" /></a>
+</p>
+
+**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.
+
+<p align="center">
+  <a href="https://github.com/anthropics/claude-code" title="Claude Code"><img src="assets/harnesses/anthropic.svg" height="32" alt="Claude Code" /></a>
+  &nbsp;&nbsp;&nbsp;&nbsp;
+  <a href="https://github.com/openai/codex" title="Codex CLI"><img src="assets/harnesses/openai.svg" height="32" alt="Codex CLI" /></a>
+  &nbsp;&nbsp;&nbsp;&nbsp;
+  <a href="https://github.com/google-gemini/gemini-cli" title="Gemini CLI"><img src="assets/harnesses/google.svg" height="32" alt="Gemini CLI" /></a>
+  &nbsp;&nbsp;&nbsp;&nbsp;
+  <a href="https://cursor.com" title="Cursor"><img src="assets/harnesses/cursor.svg" height="32" alt="Cursor" /></a>
+  &nbsp;&nbsp;&nbsp;&nbsp;
+  <a href="https://github.com/sst/opencode" title="OpenCode"><img src="assets/harnesses/opencode.png" height="32" alt="OpenCode" /></a>
+  &nbsp;&nbsp;&nbsp;&nbsp;
+  <a href="https://github.com/openclaw/openclaw" title="OpenClaw"><img src="assets/harnesses/openclaw.svg" height="36" alt="OpenClaw" /></a>
+  &nbsp;&nbsp;&nbsp;&nbsp;
+  <a href="https://github.com/NousResearch/hermes-agent" title="Hermes Agent"><img src="assets/harnesses/hermes.png" height="32" alt="Hermes Agent" /></a>
+</p>
+
+https://github.com/user-attachments/assets/cf0b2248-6672-4458-8027-b88525572f3e
 
 ```bash
-curl -fsSL agents-cli.sh | sh
-# or
 npm install -g @phnx-labs/agents-cli
+# or
+bun install -g @phnx-labs/agents-cli
 ```
 
-Also available as `ag` — all commands work with both `agents` and `ag`.
-
-## Table of contents
-
-- [Run any agent, same interface](#run-any-agent-same-interface)
-- [Put agents on a team](#put-agents-on-a-team)
-- [Non-interactive usage](#non-interactive-usage)
-- [Search sessions fast](#search-sessions-fast)
-- [Pin agent versions per project](#pin-agent-versions-per-project)
-- [Install skills, MCP servers, and commands once](#install-skills-mcp-servers-and-commands-once--every-agent-gets-them)
-- [Quick reference](#quick-reference)
-- [Skill format](#skill-format)
+Source: [github.com/phnx-labs/agents-cli](https://github.com/phnx-labs/agents-cli)
+
+Also available as `ag` -- all commands work with both `agents` and `ag`.
+
+- [Pin versions per project](#pin-versions-per-project)
+- [One config, every agent](#one-config-every-agent)
+- [Run any agent](#run-any-agent)
+- [Sessions across agents](#sessions-across-agents)
+- [Run open models through Claude Code](#run-open-models-through-claude-code)
+- [Teams](#teams)
+- [Secrets](#secrets)
+- [Routines](#routines)
+- [PTY](#pty)
+- [Portable setup](#portable-setup)
+- [Private skills](#private-skills)
 - [Compatibility](#compatibility)
 - [FAQ](#faq)
-- [Contributing](#contributing)
-- [License](#license)
 
 ---
 
-## Run any agent, same interface
+## Pin versions per project
 
 ```bash
-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"
-```
+# This project needs claude@2.0.65 -- newer versions changed tool calling.
+agents use claude@2.0.65 -p
 
-Each agent resolves to the project-pinned version, with the right skills, MCP servers, and permissions already synced. No setup between steps -- just run.
+# The monorepo uses codex@0.116.0 across the team.
+agents use codex@0.116.0 -p
+```
 
-`agents run` also passes through environment overrides to the spawned CLI, so Claude can target any Anthropic-compatible endpoint:
+This creates an `agents.yaml` at the project root:
 
-```bash
-agents run claude "Reply with exactly: agents-qwen route ok" \
-  --mode full \
-  --model qwen3.6:35b \
-  --env ANTHROPIC_BASE_URL=https://ollama.example.com \
-  --env ANTHROPIC_AUTH_TOKEN="$(security find-generic-password -a "$USER" -s ollama-auth-token -w)" \
-  --env ANTHROPIC_MODEL=qwen3.6:35b \
-  --env ANTHROPIC_SMALL_FAST_MODEL=qwen3.6:35b
+```yaml
+# agents.yaml (commit this to your repo)
+agents:
+  claude: "2.0.65"
+  codex: "0.116.0"
 ```
 
-This makes agent pipelines possible. Chain agents by strength, swap one for another, script them in CI -- the interface stays the same:
+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.
 
 ```bash
-# Friday night code review
-agents run claude "Review all PRs merged this week, summarize risks" \
-  | agents run codex "Write regression tests for the top 3 risks"
-
-# Same pipeline, different project -- different agent versions, same commands
-cd ../other-project
-agents run claude "Review all PRs merged this week, summarize risks"
-# ^ resolves to claude@2.0.0 here instead of claude@2.1.89
+agents add claude@2.0.65     # Install a specific version
+agents add codex@latest       # Install latest
+agents view                   # See everything installed
 ```
 
-Supports plan (read-only) and edit modes, effort levels that map to the right model per agent, and JSON output for scripting.
-
 ---
 
-## Put agents on a team
-
-`agents run` runs one agent synchronously. **Teams** run many agents on the same task, in the background, with coordination.
+## One config, every agent
 
 ```bash
-agents teams create auth-feature
+# Set up the Notion MCP server once.
+agents install mcp:com.notion/mcp
 
-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    # launches teammates whose --after deps are done
-agents teams status auth-feature   # who's working, what they've changed, what they said
-agents teams disband auth-feature  # stop everyone, clean up
+# It's now registered with Claude Code, Codex, Gemini CLI, and Cursor.
+agents mcp list
 ```
 
-Each teammate runs detached. Close your terminal; they keep working. Check in whenever.
+Skills, slash commands, rules, hooks, and permissions work the same way -- install once in `~/.agents/`, synced to every agent's native format automatically.
 
-- `--name alice` gives a teammate a handle. Refer to them by name everywhere (`teams rm auth alice`, `teams logs alice`).
-- `--after name1,name2` stages a teammate as pending. `teams start` fires the ones whose blockers are `completed`. Cycles rejected at add time; a failed blocker keeps its dependents pending so you decide what to do.
-- For Claude teammates, `agent_id` IS the Claude session UUID -- `agents sessions <agent_id> --markdown` opens the full conversation.
-- Modes match `exec`: `plan | edit | full`. `--model`, `--env KEY=VALUE`, `--cwd` all passthroughs too.
-- `teams ls` filters: substring query, `--agent claude[@version]`, `--status working|done|failed|empty`, `--since 2h --until 30d`.
-- Non-TTY output is valid JSON by default, with a `cursor` field in every `status` response for efficient delta polling (`--since <cursor>`).
+```bash
+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
+```
 
-State lives in `~/.agents/teams/`. Teammates survive terminal restarts. Synced config (commands, skills, rules, MCP servers, hooks, permissions) applies to teammates the same way it applies to `agents run` -- one config, both flows.
+Write one `AGENTS.md`. It becomes `CLAUDE.md` for Claude Code, `GEMINI.md` for Gemini CLI, `.cursorrules` for Cursor.
 
 ---
 
-## Non-interactive usage
-
-Other coding agents usually run in non-TTY shells. `agents` now supports that mode directly:
+## Run any agent
 
 ```bash
-agents add codex@latest --yes
-agents use claude@2.1.79 --yes
-agents commands add --names review-pr,debug --agents codex@0.113.0
-agents skills add --names agents-cli --agents claude@default
-agents install ./team-agent-pack --agents codex@0.113.0
-agents mcp add postgres --agents claude@2.1.79 -- npx -y @modelcontextprotocol/server-postgres
-agents mcp register postgres
-agents sessions <session-id> --markdown
-agents routines view <job-name>
+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"
 ```
 
-Rules for automation:
+Each resolves to the project-pinned version with skills, MCP servers, and permissions already synced.
 
-- Pass explicit names or IDs instead of relying on pickers.
-- Use `--yes` when a command would otherwise ask for default sync or confirmation choices.
-- Use `--names` with `commands`, `skills`, `hooks`, `rules`, and `permissions` to install from central storage without a checkbox prompt.
-- Use `agent@version` or `agent@default` with `--agents` when you need an exact managed version.
-- Long `view` commands print directly in non-interactive shells instead of opening `less`.
+### Rate-limited? Keep working.
 
-If a command still needs a human-only picker, it now exits with a plain-text hint that shows the matching non-interactive form.
+```bash
+# 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.
 
-## Search sessions fast
+```bash
+# 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.
 
-Interactive terminals now get a live-search picker for sessions:
+### Chain agents
 
 ```bash
-agents sessions
-agents sessions --agent codex
-agents sessions --project agents-cli
-agents sessions --agent gemini "session discovery"
+agents run claude "Review PRs merged this week, summarize risks" \
+  | agents run codex "Write regression tests for the top 3 risks"
 ```
 
-What you can type into the picker:
+Supports plan (read-only) and edit modes, effort levels, JSON output for scripting, and timeout limits.
 
-- Session ID or short ID
-- Prompt text / topic text
-- Project name
-- Account email
-- Agent name or version
+### One protocol, every harness
+
+```bash
+# Typed event stream instead of raw stdout. Same command, any supported agent.
+agents run claude "review this diff" --acp --json
+```
 
-The shared `Agent` column also shows the resolved agent version when it is known, so filtered lists read like `claude@2.1.110`, `codex@0.113.0`, `gemini@0.29.5`, and `opencode@1.2.6`.
+`--acp` routes through the [Agent Client Protocol](https://agentclientprotocol.com/) 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.
 
-Pass `<id>` (with `--markdown`, `--json`, or filter flags like `--include`, `--exclude`, `--first`, `--last`) in non-interactive shells when you already know the session you want.
+Works today with claude, codex, gemini, cursor, opencode, openclaw. Other harnesses keep running on the direct-exec path.
 
 ---
 
-## Pin agent versions per project
+## Sessions across agents
+
+When you run multiple agents, conversations scatter across tools. Session search brings them together.
 
 ```bash
-agents add claude@2.0.0             # Install specific version
-agents use claude@2.0.0 -p          # Pin to this project
+# 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
 ```
 
-Like `.nvmrc` for Node -- different projects use different agent versions. A shim system reads `.agents-version` and routes to the right binary automatically. No other tool does this for AI agents.
+Interactive picker when you're in a terminal. Structured output (`--json`, `--markdown`, filtered by role or turn count) when piped.
 
-When you switch versions, configs are backed up and resources are re-synced. Each version gets its own isolated home directory with the right skills, commands, and permissions already in place.
+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](docs/05-sessions.md) for the schema and [docs/06-observability.md](docs/06-observability.md) for the consumption patterns.
 
 ---
 
-## Install skills, MCP servers, and commands once -- every agent gets them
-
-### Skills
+## Run open models through Claude Code (experimental)
 
-Skills are reusable knowledge packs -- rules, patterns, and expertise that make your agents better at specific tasks. Install once, available everywhere.
+> **Note:** Profiles are experimental. Enable with `agents beta profiles enable`.
 
 ```bash
-agents skills add gh:yourname/python-expert     # Install from GitHub
-agents skills add ./my-skills                    # Install from local path
-agents skills list                               # See what's installed
-agents skills view python-expert                 # View skill details and rules
+# 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"
 ```
 
-A skill is a directory with a `SKILL.md` and optional rule files:
-
-```
-python-expert/
-  SKILL.md              # Metadata + description
-  rules/
-    type-hints.md       # Individual rules your agents follow
-    error-handling.md
-    testing.md
+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/`:
+
+```yaml
+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
 ```
 
-Skills are stored centrally in `~/.agents/skills/` and distributed to each agent's native skill directory. Write once, every agent gets it.
+Profile YAML has no secrets -- safe to `agents repo push` to a shared repo. `agents profiles presets` lists the full catalog.
 
-### Install MCP servers everywhere at once
+---
 
-```bash
-agents search notion                    # Find MCP servers
-agents install mcp:com.notion/mcp       # Install + register with ALL agents
-agents mcp list                         # See what's registered
-```
+## Teams
 
-No more running `claude mcp add`, then `codex mcp add`, then editing Gemini's config file.
+```bash
+agents teams create auth-feature
 
-### Manage slash commands
+# 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
 
-```bash
-agents commands add gh:yourname/commands    # Install from repo
-agents commands list                        # See all commands
-agents commands view review-pr              # View command content
+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
 ```
 
-Commands are markdown files with a description. The CLI handles format conversion automatically -- markdown for Claude/Gemini/Cursor, TOML for Codex.
+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](docs/06-observability.md).
+
+---
 
-### Sync your entire setup
+## Secrets
 
 ```bash
-agents push                       # Snapshot your config to git
-agents pull                       # Restore on any machine
+# 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
 ```
 
-`push` captures your current agent versions and MCP registrations into `~/.agents/`. `pull` does the real work — it installs agent CLIs, registers MCP servers, syncs resources (commands, skills, rules, hooks, permissions) into each agent's config directory, sets up PATH shims, and configures defaults. One command, fully configured machine.
+<p align="center">
+  <img src="assets/secrets.svg" alt="How agents-cli secrets work: stripe.yml holds a pointer, the macOS Keychain holds the value, agents-cli resolves at runtime and injects the env into the child process" width="100%" />
+</p>
+
+Merge order: profile env < `--secrets` < `--env K=V`. A missing keychain item aborts before the child starts.
 
-### Interactive PTY sessions
+### Cross-machine sync via iCloud Keychain
 
-Give your agents the ability to interact with full-screen terminal programs -- REPLs, TUIs, interactive installers, anything that needs a real terminal.
+Pass `--icloud-sync` when creating a bundle and the values are written to the iCloud-synced keychain. Sign into the same iCloud account on another Mac (with iCloud Keychain enabled) and the values appear there within seconds — no copy-paste, no `.env` files emailed to yourself, no shared secret stores.
 
 ```bash
-SID=$(agents pty start)                              # Start a session
-agents pty exec $SID "python3"                       # Launch Python REPL
-agents pty screen $SID                               # See what's on screen
-agents pty write $SID "print('hello')\n"             # Type into it
-agents pty screen $SID                               # See the result
-agents pty write $SID "exit()\n"                     # Quit
-agents pty stop $SID                                 # Clean up
+# 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 add npm-tokens NPM_TOKEN          # the value is already there;
+                                                 # you only need the bundle YAML locally
 ```
 
-A sidecar server holds PTY sessions alive between CLI calls. `screen` renders the terminal as clean text (no ANSI codes) using xterm-headless -- so agents see exactly what a human would see. Sessions auto-clean after 30 minutes of idle.
+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` use `/usr/bin/security` and stay device-local.
+
+Bundle YAML files (`~/.agents/secrets/*.yml`) are not synced — only the secret values. Push the YAMLs across machines via `agents repo push` if you want full bundle definitions to follow.
+
+---
 
-### Schedule agents as routines
+## Routines
 
 ```bash
+# 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"
-# The scheduler auto-starts on first add — no separate daemon command needed.
 
-agents routines list                   # See all jobs
-agents routines status                 # Check scheduler and upcoming runs
-agents routines logs daily-digest      # Check execution logs
+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.
 
-### Manage rules/instructions, hooks, and permissions
+---
 
-Each agent has its own instruction file format -- Claude uses `CLAUDE.md`, Codex uses `AGENTS.md`, Cursor uses `.cursorrules`. The CLI manages all of them under one command.
+## PTY
 
 ```bash
-agents rules list                 # Show what's installed per agent
-agents rules add gh:team/rules    # Install and sync to all agents
-agents rules view claude          # View rule file content
+# 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
 ```
 
-Write one `AGENTS.md`, and it gets renamed and synced to each agent's native format automatically.
+A sidecar server holds sessions alive between CLI calls. `screen` renders via xterm-headless. Sessions auto-clean after 30 minutes idle.
+
+---
+
+## Portable setup
 
 ```bash
-agents hooks list                 # Show lifecycle hooks
-agents hooks add gh:team/hooks    # Install hook scripts
+# New machine? One command.
+agents init
+
+# Installs CLIs, registers MCP servers, syncs skills/commands/rules/hooks,
+# sets up shims, configures defaults. Done.
 
-agents permissions list           # Show permission sets
-agents permissions add ./perms    # Install permission groups
+agents repo push     # Snapshot your config to git
 ```
 
-Hooks trigger on agent lifecycle events. Permissions are auto-converted between agent-specific formats (Claude's allow/deny, Codex's approval policies, OpenCode's patterns).
+### How config is layered
 
----
+Two repos with the same shape, different roles:
 
-## Quick Reference
+| 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](https://github.com/phnx-labs/.agents-system) |
+| `~/.agents/` | **User repo** — your personal additions and overrides. This is what `agents repo push`/`pull` syncs. | You |
 
-```bash
-# Agent versions
-agents add claude@latest          # Install agent CLI
-agents remove codex@0.5.0        # Remove specific version
-agents use claude@2.0.0           # Set global default
-agents use claude@2.0.0 -p        # Pin to this project
-agents list                       # Show all installed versions
-agents view claude                # Show version details + resources
-
-# Skills
-agents skills list                # List installed skills
-agents skills add <source>        # Install from git/local
-agents skills remove <name>       # Remove a skill
-agents skills view <name>         # View skill details
-
-# Commands
-agents commands list              # List slash commands
-agents commands add <source>      # Install commands
-agents commands view <name>       # View command content
-
-# Rules / Instructions
-agents rules list                 # List per-agent instruction files
-agents rules add <source>         # Install from git/local
-agents rules remove <agent>       # Remove rule file
-agents rules view <agent>         # View rule file content
-
-# MCP servers
-agents search <query>             # Find in registry
-agents install mcp:<name>         # Install + register
-agents mcp list                   # Show registered servers
-agents mcp add <name> <cmd>       # Register manually
-
-# Sync
-agents pull [source]              # Sync from repo
-agents push                       # Push changes back
-
-# Drive
-agents drive remote <user@host>   # Set sync target
-agents drive pull                  # Pull sessions from remote
-agents drive push                  # Push sessions to remote
-agents drive attach                # Use drive as active agent home
-agents drive detach                # Restore to version home
-agents drive status                # Show drive state
-
-# Execution
-agents run <agent> <prompt>      # Run agent
-agents sessions <id> --markdown   # Read a session by exact ID
-agents sessions --agent codex     # Interactive filtered session search
-agents sessions --project agents  # Interactive project-scoped session search
-agents routines add <name>        # Schedule a job (scheduler auto-starts)
-agents routines list              # Show all jobs
-agents routines status            # Check scheduler status + upcoming runs
-
-# Teams (orchestrate multiple agents on a shared task)
-agents teams create <team>             # Start a new team
-agents teams add <team> <agent> <task> # Add a teammate (runs immediately)
-  --name alice                         #   give them a handle
-  --after alice,bob                    #   stage as pending until deps complete
-  --mode plan|edit|full                #   permissions
-  --model <model> --env K=V            #   same passthroughs as exec
-agents teams start <team>              # Launch pending teammates whose deps are done
-agents teams status <team>             # Team standup (pass --since <cursor> for deltas)
-agents teams ls                        # List teams (--agent, --status, --since filters)
-agents teams remove <team> <teammate>  # Let one teammate go (name or UUID prefix)
-agents teams disband <team>            # Stop everyone, remove the team
-agents teams logs <teammate>           # Read their raw log
-agents teams doctor                    # Check which agents can join a team
-
-# PTY sessions
-agents pty start                  # Start a PTY session (returns ID)
-agents pty exec <id> <command>    # Run a command in the session
-agents pty screen <id>            # Render terminal as clean text
-agents pty write <id> <input>     # Send keystrokes (\n \t \e \xHH)
-agents pty read <id>              # Read raw output
-agents pty signal <id> INT        # Send signal
-agents pty list                   # Show active sessions
-agents pty stop <id>              # Kill a session
-agents pty server status          # Check sidecar server
-```
+**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](docs/00-concepts.md) for the full mental model: DotAgents repos, resource kinds, and how resolution works end-to-end.
 
 ---
 
-## Skill Format
+## Private skills
 
-Create a `SKILL.md` with YAML frontmatter:
+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.
 
-```markdown
----
-name: python-expert
-description: Python code analysis, type hints, and testing patterns
-author: Your Name
-version: 1.0.0
-keywords: [python, testing, types]
----
+```bash
+# Add a private repo for work-only skills
+agents repo add gh:yourname/.agents-work
 
-# Python Expert
+# Add with a custom alias
+agents repo add git@github.com:acme/team-skills.git --as acme
 
-High-level description of what this skill teaches your agents.
+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
 ```
 
-Add rule files in a `rules/` subdirectory -- each rule is a markdown file with specific guidance your agents follow during conversations.
+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.
 
 ---
 
 ## Compatibility
 
-| Agent | Versions | MCP | Commands | Skills | Rules | Hooks | Permissions | Routines | Teams |
-|-------|----------|-----|----------|--------|-------|-------|-------------|----------|-------|
-| Claude | yes | yes | yes | yes | CLAUDE.md | yes | yes | yes | yes |
-| Codex | yes | yes | yes | yes | AGENTS.md | yes | yes | yes | yes |
-| Gemini | yes | yes | yes | yes | GEMINI.md | yes | -- | yes | yes |
-| Cursor | yes | yes | yes | yes | .cursorrules | -- | -- | -- | yes |
-| OpenCode | yes | yes | yes | yes | AGENTS.md | yes | yes | -- | yes |
-| OpenClaw | yes | yes | -- | yes | workspace/AGENTS.md | yes | -- | -- | -- |
+| 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?
 
-Each agent CLI has its own config format, its own MCP setup, its own version management, its own skill system. If you use more than one, you end up maintaining 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, session discovery across all of them, and project-pinned versions like `.nvmrc`.
+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.
 
-### Is this like `nvm` / `mise` / `asdf` but for AI agents?
+### How do I share my agent setup with my team?
 
-For version management, yes — that's the closest analogue. `agents-cli` reads `.agents-version` in a project, walks up the directory tree, and routes `claude` / `codex` / `gemini` to the correct installed binary per project. But `agents` also manages agent-native resources (skills, MCP servers, slash commands, hooks, permissions) that language version managers don't touch.
+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.
 
-### How is this different from Vercel's Open Agents?
+### Do I need to write separate rules for each agent (CLAUDE.md, GEMINI.md, etc.)?
 
-Open Agents is a hosted cloud product. `agents-cli` is a local-first open client — your agents run on your machine against your API keys, no SaaS layer in between. Part of an open stack for AI coding agents; cloud runner coming separately.
+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. `agents-cli` reads API keys from your shell environment or each agent CLI's existing auth (it never writes a credential file, never reads one you didn't already set up). No telemetry, no phone-home. All state lives in `~/.agents/` and each agent's own config dir.
+No. API keys come from your shell environment or each agent CLI's existing auth. No telemetry, no phone-home. User content lives in `~/.agents/`; operational state (versions, shims, sessions, caches) lives in `~/.agents-system/`.
+
+### 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?
 
-### Do I need Node.js? Bun?
+The installer tries Bun first (faster), falls back to npm. Node 18+ required at runtime.
 
-Either works. The installer tries Bun first (faster), falls back to npm. Node 18+ is required at runtime. No other build tools needed.
+### Can I use it in CI?
 
-### Which platforms are supported?
+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.
 
-macOS and Linux today. Windows via WSL works but isn't first-class. Native Windows support is on the roadmap.
+### What happens to my config when I switch versions?
 
-### Can I use `agents` in CI?
+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/`.
 
-Yes — `agents run` is non-interactive by default with `--yes` flags for every prompt and JSON output for parsing. The [non-interactive usage](#non-interactive-usage) section covers the automation-friendly flags.
+### Does session search use RAG or semantic search?
 
-### Can I add support for a new agent CLI?
+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.
 
-Yes. Agents are defined in [src/lib/agents.ts](src/lib/agents.ts) — each is a config object declaring commands dir, memory file format, and capabilities. Open an issue or PR.
+### 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](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 that builds on top of the same runtime. You can use `agents-cli` on its own — no Rush account required, no upsell.
+`agents-cli` is an open client maintained by Phoenix Labs. Rush is a separate product. No Rush account required, no upsell.
 
 ## Contributing
 
-PRs and issues welcome. To develop locally:
-
 ```bash
 git clone https://github.com/phnx-labs/agents-cli
 cd agents-cli
-bun install
-bun run build
-bun test
+bun install && bun run build && bun test
 ```
 
-The CLI entry is [src/index.ts](src/index.ts). Commands live in [src/commands/](src/commands/); shared libraries in [src/lib/](src/lib/). Tests sit next to source as `*.test.ts` and run under `vitest` (see [CLAUDE.md](CLAUDE.md) for the full style guide).
-
-For a full comparison with other tools in the ecosystem — Rivet, Agentloom, mise, skills.sh, cass, Microsoft APM — see [docs/04-landscape.md](docs/04-landscape.md).
+Commands in [src/commands/](src/commands/), libraries in [src/lib/](src/lib/), tests as `*.test.ts` under vitest. [CLAUDE.md](CLAUDE.md) has the full style guide. [docs/04-landscape.md](docs/04-landscape.md) covers the competitive landscape.
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+MIT -- see [LICENSE](./LICENSE).