@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/README.md

@@ -1,537 +1,448 @@
-# 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)
-- [Run open-source models through Claude Code](#run-open-source-models-through-claude-code)
-- [Keep secrets out of plaintext env files](#keep-secrets-out-of-plaintext-env-files)
-- [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
+
+# The monorepo uses codex@0.116.0 across the team.
+agents use codex@0.116.0 -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.
+This creates an `agents.yaml` at the project root:
 
-`agents run` also passes environment overrides to the spawned CLI. For one-off flags this looks like `--env KEY=VALUE`; for repeatable provider setups see [profiles](#run-open-source-models-through-claude-code) below.
+```yaml
+# agents.yaml (commit this to your repo)
+agents:
+  claude: "2.0.65"
+  codex: "0.116.0"
+```
 
-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.
-
 ---
 
-## Run open-source models through Claude Code
+## One config, every agent
 
-`agents profiles` saves a named bundle of (host CLI, endpoint, model, keychain-backed auth). Ship a preset, paste the API key once, then invoke any open-source model as a first-class agent — no shell function, no plaintext token, no proxy.
+```bash
+# 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.
 
 ```bash
-agents profiles add kimi                # prompts for OpenRouter key, stores in Keychain
-agents run kimi "refactor this file"    # Claude Code UI, Kimi K2.5 responses
+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
 ```
 
-Built-in presets (all via OpenRouter, one shared key):
+Write one `AGENTS.md`. It becomes `CLAUDE.md` for Claude Code, `GEMINI.md` for Gemini CLI, `.cursorrules` for Cursor.
 
-| Preset | Model | Notes |
-|---|---|---|
-| `kimi` | `moonshotai/kimi-k2.5` | #1 HumanEval (99%), top Kimi. Reasoning — interactive only. |
-| `kimi-chat` | `moonshotai/kimi-k2-0905` | Non-reasoning, print-safe for `agents run`. |
-| `minimax` | `minimax/minimax-m2.5` | #1 SWE-bench Verified (80.2%). Reasoning. |
-| `glm` | `z-ai/glm-5` | #1 Chatbot Arena among open-weight (1451 ELO). |
-| `qwen` | `qwen/qwen3-coder-next` | Latest coding Qwen, sparse MoE 80B/3B active. Print-safe. |
-| `deepseek` | `deepseek/deepseek-chat-v3-0324` | Latest non-reasoning DeepSeek Chat. Print-safe. |
+---
 
-`agents profiles presets` lists the catalog. `agents profiles view <name>` shows the env, model, and keychain status.
+## Run any agent
 
-**How it works:** a profile swaps the *model* while keeping Claude Code as the *agent runtime* — same UI, slash commands, skills, MCP tools, permission system. Under the hood it sets `ANTHROPIC_BASE_URL` + `ANTHROPIC_MODEL` and pulls `ANTHROPIC_AUTH_TOKEN` from Keychain at spawn time.
+```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"
+```
 
-Profile YAML lives in `~/.agents/profiles/<name>.yml` with no secrets — safe to `agents push` to a shared repo. Keys live only in macOS Keychain; rotate with `agents profiles login <provider>`.
+Each resolves to the project-pinned version with skills, MCP servers, and permissions already synced.
 
-**Custom endpoints** — for self-hosted models (Ollama, vLLM) or other aggregators, drop a YAML file directly:
+### Rate-limited? Keep working.
 
-```yaml
-# ~/.agents/profiles/local-qwen.yml
-name: local-qwen
-host: { agent: claude }
-env:
-  ANTHROPIC_BASE_URL: https://ollama.internal
-  ANTHROPIC_MODEL: qwen3.6:35b
-  ANTHROPIC_SMALL_FAST_MODEL: qwen3.6:35b
-auth:
-  envVar: ANTHROPIC_AUTH_TOKEN
-  keychainItem: agents-cli.ollama.token
+```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
 ```
 
-Then `agents profiles login ollama` to store the token, and `agents run local-qwen "..."` works.
-
-**Note on `--print` and reasoning models:** Claude Code's `--print` mode consolidates response text, but returns empty when the response contains `thinking` blocks. Models flagged REASONING in the preset descriptions work fine interactively (plain `claude` launch with the same env) but not with `agents run --print`. Use the non-reasoning `-chat` variant for scripting.
+### Multiple accounts? Spread the load.
 
----
+```bash
+# Picks the signed-in account you haven't used recently.
+agents run claude "summarize recent commits" --rotate
+```
 
-## Keep secrets out of plaintext env files
+`--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 secrets` stores sensitive values (API keys, tokens, even a test credit card number) in the macOS Keychain and injects them into agents at run time. Bundle files on disk contain only references — safe to `agents push` to a shared repo.
+### Chain agents
 
 ```bash
-agents secrets add prod-stripe --description "Stripe prod + test card"
-agents secrets set prod-stripe STRIPE_SECRET_KEY          # prompts, stores in keychain
-agents secrets set prod-stripe TEST_CARD_NUMBER           # prompts, stores in keychain
-agents secrets set prod-stripe STRIPE_API_VERSION --value "2024-06-20"
-agents secrets set prod-stripe GITHUB_TOKEN --env GH_TOKEN   # read from parent shell
-agents secrets set prod-stripe GCP_CREDS --file ~/.config/gcloud/creds.json
-
-agents run claude "charge a test card" --secrets prod-stripe
+agents run claude "Review PRs merged this week, summarize risks" \
+  | agents run codex "Write regression tests for the top 3 risks"
 ```
 
-The resulting `~/.agents/secrets/prod-stripe.yml` holds only refs:
+Supports plan (read-only) and edit modes, effort levels, JSON output for scripting, and timeout limits.
 
-```yaml
-name: prod-stripe
-vars:
-  STRIPE_SECRET_KEY: keychain:STRIPE_SECRET_KEY
-  TEST_CARD_NUMBER:  keychain:TEST_CARD_NUMBER
-  STRIPE_API_VERSION: { value: "2024-06-20" }
-  GITHUB_TOKEN: env:GH_TOKEN
-  GCP_CREDS: file:~/.config/gcloud/creds.json
+### 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
 ```
 
-Merge order on `agents run` is **profile env < `--secrets <bundle>` < `--env K=V`** — a profile carries provider auth, bundles carry user-defined values, `--env` is the per-invocation override. Resolution happens right before `spawn`; a missing keychain item aborts the run before the child starts.
+`--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.
+
+Works today with claude, codex, gemini, cursor, opencode, openclaw. Other harnesses keep running on the direct-exec path.
 
 ---
 
-## Put agents on a team
+## Sessions across agents
 
-`agents run` runs one agent synchronously. **Teams** run many agents on the same task, in the background, with coordination.
+When you run multiple agents, conversations scatter across tools. Session search brings them together.
 
 ```bash
-agents teams create auth-feature
+# Where was that auth conversation? Search Claude Code, Codex, Gemini CLI, OpenCode at once.
+agents sessions "auth middleware"
 
-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
+# Filter by agent, project, or time window
+agents sessions --agent codex --since 7d
+agents sessions --project my-app
 
-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
-```
+# Read a full conversation
+agents sessions a1b2c3d4 --markdown
 
-Each teammate runs detached. Close your terminal; they keep working. Check in whenever.
+# Just the last 3 turns, user messages only
+agents sessions a1b2c3d4 --last 3 --include user
+```
 
-- `--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>`).
+Interactive picker when you're in a terminal. Structured output (`--json`, `--markdown`, filtered by role or turn count) when piped.
 
-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.
+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.
 
 ---
 
-## Non-interactive usage
+## Run open models through Claude Code (experimental)
 
-Other coding agents usually run in non-TTY shells. `agents` now supports that mode directly:
+> **Note:** Profiles are experimental. Enable with `agents beta profiles enable`.
 
 ```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>
+# 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"
 ```
 
-Rules for automation:
+Built-in presets (all via OpenRouter, one shared key):
 
-- 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`.
+| 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. |
 
-If a command still needs a human-only picker, it now exits with a plain-text hint that shows the matching non-interactive form.
+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
+```
+
+Profile YAML has no secrets -- safe to `agents repo push` to a shared repo. `agents profiles presets` lists the full catalog.
 
-## Search sessions fast
+---
 
-Interactive terminals now get a live-search picker for sessions:
+## Teams
 
 ```bash
-agents sessions
-agents sessions --agent codex
-agents sessions --project agents-cli
-agents sessions --agent gemini "session discovery"
-```
+agents teams create auth-feature
 
-What you can type into the picker:
+# 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
 
-- Session ID or short ID
-- Prompt text / topic text
-- Project name
-- Account email
-- Agent name or version
+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
+```
 
-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`.
+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`.
 
-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.
+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).
 
 ---
 
-## Pin agent versions per project
+## Secrets
 
 ```bash
-agents add claude@2.0.0             # Install specific version
-agents use claude@2.0.0 -p          # Pin to this project
+# 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
 ```
 
-Like `.nvmrc` for Node -- different projects use different agent versions. A shim system reads a project-root `agents.yaml` and routes to the right binary automatically. No other tool does this for AI agents.
+<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>
 
-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.
+Merge order: profile env < `--secrets` < `--env K=V`. A missing keychain item aborts before the child starts.
 
 ---
 
-## Install skills, MCP servers, and commands once -- every agent gets them
-
-### Skills
-
-Skills are reusable knowledge packs -- rules, patterns, and expertise that make your agents better at specific tasks. Install once, available everywhere.
+## Routines
 
 ```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
-```
-
-A skill is a directory with a `SKILL.md` and optional rule files:
+# 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
 ```
-python-expert/
-  SKILL.md              # Metadata + description
-  rules/
-    type-hints.md       # Individual rules your agents follow
-    error-handling.md
-    testing.md
-```
 
-Skills are stored centrally in `~/.agents/skills/` and distributed to each agent's native skill directory. Write once, every agent gets it.
+Jobs run sandboxed -- agents only see directories and tools you explicitly allow.
+
+---
 
-### Install MCP servers everywhere at once
+## PTY
 
 ```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
+# 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
 ```
 
-No more running `claude mcp add`, then `codex mcp add`, then editing Gemini's config file.
+A sidecar server holds sessions alive between CLI calls. `screen` renders via xterm-headless. Sessions auto-clean after 30 minutes idle.
 
-### Manage slash commands
+---
+
+## Portable setup
 
 ```bash
-agents commands add gh:yourname/commands    # Install from repo
-agents commands list                        # See all commands
-agents commands view review-pr              # View command content
+# 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
 ```
 
-Commands are markdown files with a description. The CLI handles format conversion automatically -- markdown for Claude/Gemini/Cursor, TOML for Codex.
+### How config is layered
 
-### Sync your entire setup
+Two repos with the same shape, different roles:
 
-```bash
-agents push                       # Snapshot your config to git
-agents pull                       # Restore on any machine
-```
+| 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 |
 
-`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.
+**Version pinning:** `agents.yaml` at project root pins which agent version to use (like `.nvmrc` for Node).
 
-### Interactive PTY sessions
+**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.
 
-Give your agents the ability to interact with full-screen terminal programs -- REPLs, TUIs, interactive installers, anything that needs a real terminal.
+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.
 
-```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
-```
+---
 
-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.
+## Private skills
 
-### Schedule agents as routines
+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.
 
 ```bash
-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.
+# Add a private repo for work-only skills
+agents repo add gh:yourname/.agents-work
 
-agents routines list                   # See all jobs
-agents routines status                 # Check scheduler and upcoming runs
-agents routines logs daily-digest      # Check execution logs
+# 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 clone
 ```
 
-Jobs run sandboxed -- agents only see directories and tools you explicitly allow.
+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.
 
-### 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.
+## Compatibility
 
-```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
-```
+| 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 | -- | -- | -- | -- | -- |
 
-Write one `AGENTS.md`, and it gets renamed and synced to each agent's native format automatically.
+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.
 
-```bash
-agents hooks list                 # Show lifecycle hooks
-agents hooks add gh:team/hooks    # Install hook scripts
+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`.
 
-agents permissions list           # Show permission sets
-agents permissions add ./perms    # Install permission groups
-```
+## FAQ
 
-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).
+### 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`.
 
-## Quick Reference
+### Is it free?
 
-```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
-
-# Secrets (keychain-backed env bundles, injected at run time)
-agents secrets list                       # Show all bundles
-agents secrets add <name>                 # Create an empty bundle
-agents secrets set <bundle> <KEY>         # Prompt, store in keychain, write ref
-agents secrets set <bundle> <KEY> --value <v>      # Store as YAML literal
-agents secrets set <bundle> <KEY> --env <VAR>      # Inherit from parent shell
-agents secrets set <bundle> <KEY> --file <path>    # Read from a file at run time
-agents secrets view <name> [--reveal]     # Show bundle (masked by default)
-agents secrets import <name> --from .env  # Import a dotenv file into keychain
-agents secrets rm <name>                  # Delete bundle and purge keychain
-agents run <agent> "..." --secrets <name> # Inject a bundle (repeatable)
-
-# 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
-```
+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?
 
-## Skill Format
+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.
 
-Create a `SKILL.md` with YAML frontmatter:
+### How does version switching actually work?
 
-```markdown
----
-name: python-expert
-description: Python code analysis, type hints, and testing patterns
-author: Your Name
-version: 1.0.0
-keywords: [python, testing, types]
----
+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.
 
-# Python Expert
+### How do I share my agent setup with my team?
 
-High-level description of what this skill teaches your agents.
-```
+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.
 
-Add rule files in a `rules/` subdirectory -- each rule is a markdown file with specific guidance your agents follow during conversations.
+### 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.
 
-## Compatibility
+### Do agents use API keys or subscriptions?
 
-| 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 | -- | -- | -- |
+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.
 
-## FAQ
+### Does it store my API keys or send telemetry?
 
-### Why use `agents` instead of `claude` / `codex` / `gemini` directly?
+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/`.
 
-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`.
+### Which platforms?
 
-### Is this like `nvm` / `mise` / `asdf` but for AI agents?
+macOS and Linux. Windows via WSL works but isn't first-class yet.
 
-For version management, yes — that's the closest analogue. `agents-cli` reads a project-root `agents.yaml`, 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.
+**macOS-only features:** Keychain-based secrets (`agents secrets`, `agents profiles login`) require macOS. On Linux, use environment variables or `.env` files for API keys. Native Linux credential store support is planned.
 
-### How is this different from Vercel's Open Agents?
+### Do I need Node.js?
 
-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.
+The installer tries Bun first (faster), falls back to npm. Node 18+ required at runtime.
 
-### Does it store my API keys or send telemetry?
+### Can I use it in CI?
 
-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.
+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.
 
-### Do I need Node.js? Bun?
+### What happens to my config when I switch versions?
 
-Either works. The installer tries Bun first (faster), falls back to npm. Node 18+ is required at runtime. No other build tools needed.
+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/`.
 
-### Which platforms are supported?
+### Does session search use RAG or semantic search?
 
-macOS and Linux today. Windows via WSL works but isn't first-class. Native Windows support is on the roadmap.
+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.
 
-### Can I use `agents` in CI?
+### How do I use custom or local models?
 
-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.
+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 CLI?
+### Can I add support for a new agent?
 
-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.
+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).