@swarmify/agents-cli 1.11.3 → 1.13.0

package/CHANGELOG.md

@@ -1,6 +1,45 @@
 # Changelog
 
-## 1.11.3
+## Unreleased
+
+**Scheduler merged into `routines`; top-level help simplified**
+
+- `agents routines add` now auto-starts the background scheduler when it is not already running. First-time users no longer need a separate `daemon start` step — the common path is just `routines add`.
+- New subcommands mirror the old daemon controls under `routines`: `agents routines start`, `stop`, `status`, `scheduler-logs`. The word "daemon" is no longer exposed in user-facing help.
+- `agents daemon <start|stop|status|logs>` is **deprecated**. It still works but prints a migration warning and is hidden from top-level help. Will be removed in v2.0.
+- Top-level help restructured: the old "Automation" grab-bag is gone. Commands are now grouped as **Run agents** (`run`, `teams`, `sessions`), **Schedule** (`routines`), and **Helpers** (`pty`).
+
+**Dev: sqlite auto-rebuild on `bun run test`**
+
+- Added `scripts/rebuild-sqlite.sh` and a `pretest` hook. The script probes `better-sqlite3` by opening an in-memory database and only rebuilds (plain `node-gyp rebuild --release`, no Electron flags) when the probe fails. Fixes the napi ABI mismatch that `bun install` sometimes leaves behind.
+
+**Default upstream moved to `phnx-labs/.agents`**
+
+- `DEFAULT_SYSTEM_REPO` now resolves to `gh:phnx-labs/.agents` — a curated, org-owned upstream. `agents pull` (no args) and `agents fork` target the new repo on fresh machines.
+- Existing users whose upstream still points at `muqsitnawaz/.agents` see a one-time nudge on `agents pull --upstream` with the command to switch. Nothing else breaks; legacy remotes continue to work.
+
+**Consolidate sessions command**
+
+- Removed `agents sessions list` and `agents sessions view` subcommands; `agents sessions` is now a single smart command
+- Positional query resolves to a session ID (renders directly), a path (`.`, `../`, `/path`) to filter by project, or free text for search
+- Claude `/resume` history fallback (previously only in `view`) now fires from the top-level command too
+- Picker shows the selected-session preview by default; space hides it
+
+**Session view flags: filters + formats split cleanly**
+
+- Formats: default is the activity summary; `--markdown` renders the full conversation (user + assistant + thinking + tool calls) as markdown; `--json` emits normalized events
+- Filters compose orthogonally: `--include <roles>` / `--exclude <roles>` (values: `user`, `assistant`, `thinking`, `tools`), plus `--first N` / `--last N` to slice by turn (a turn starts at each user message)
+- Any filter flag without `--markdown`/`--json` defaults to markdown output — summary is an aggregate view so filters would be meaningless there
+- Mutual exclusion: `--include` vs `--exclude`, `--first` vs `--last`
+- Removed `--transcript`, `--trace`, `--timeline`, and `--role` (replaced by the above)
+
+## 1.12.0
+
+**JSON output for sessions list**
+
+- Added `--json` flag to `agents sessions list` and `agents sessions` for programmatic use
+- Output is a JSON array of session metadata (id, shortId, agent, version, account, project, cwd, filePath, topic, messageCount, tokenCount, timestamp)
+- Enables the Swarmify VS Code extension's "Agents: Session Resume" and "Agents: Session Trace" pickers
 
 **OpenClaw workspace-aware sessions**
 

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phoenix Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,344 +1,320 @@
-# agents
+<p align="center">
+  <img src="assets/logo.png" alt="agents" width="120" />
+</p>
 
-**The package manager and runtime for AI coding agents.**
+<h1 align="center">agents</h1>
 
-Install versions. Install skills. Run any agent through one interface. Build pipelines across Claude, Codex, Gemini, Cursor, OpenCode, and more.
+<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://agents-cli.sh"><img src="https://img.shields.io/badge/homepage-agents--cli.sh-blue?style=flat-square" alt="homepage" /></a>
+</p>
+
+**One CLI for all your AI coding agents.** Pin versions per project. Share config across Claude Code, Codex, Gemini CLI, and Cursor. Stop setting up the same MCP server three times.
+
+<p align="center">
+  <video src="https://github.com/phnx-labs/agents-cli/raw/main/assets/demo.mp4" autoplay loop muted playsinline width="800"></video>
+</p>
 
 ```bash
-npm install -g @swarmify/agents-cli
+curl -fsSL agents-cli.sh | sh
+# or
+npm install -g @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)
+- [Compatibility](#compatibility)
+- [FAQ](#faq)
+
 ---
 
-## Run any agent. Same interface.
+## Pin versions per project
 
 ```bash
-agents exec claude "Find all auth vulnerabilities in src/"
-agents exec codex "Fix the issues Claude found"
-agents exec 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.
-
-`agents exec` also passes through environment overrides to the spawned CLI, so Claude can target any Anthropic-compatible endpoint:
-
-```bash
-agents exec claude "Reply with exactly: agents-qwen route ok" \
-  --mode full \
-  --model qwen3.6:35b \
-  --env ANTHROPIC_BASE_URL=https://ollama.427yosemite.com \
-  --env ANTHROPIC_AUTH_TOKEN="$(security find-generic-password -a "$USER" -s yosemite-ollama-auth-token -w)" \
-  --env ANTHROPIC_MODEL=qwen3.6:35b \
-  --env ANTHROPIC_SMALL_FAST_MODEL=qwen3.6:35b
+# The monorepo uses codex@0.116.0 across the team.
+agents use codex@0.116.0 -p
 ```
 
-This makes agent pipelines possible. Chain agents by strength, swap one for another, script them in CI -- the interface stays the same:
+Like `.nvmrc` for Node. A shim reads `agents.yaml` from the project root and routes `claude` / `codex` / `gemini` to the right version automatically. Each version gets its own isolated home -- switching backs up config and re-syncs resources.
 
 ```bash
-# Friday night code review
-agents exec claude "Review all PRs merged this week, summarize risks" \
-  | agents exec codex "Write regression tests for the top 3 risks"
-
-# Same pipeline, different project -- different agent versions, same commands
-cd ../other-project
-agents exec 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.
-
 ---
 
-## Non-interactive usage
-
-Other coding agents usually run in non-TTY shells. `agents` now supports that mode directly:
+## One config, every 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 view <session-id>
-agents routines view <job-name>
+# 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
 ```
 
-Rules for automation:
+Skills, slash commands, rules, hooks, and permissions work the same way -- install once in `~/.agents/`, synced to every agent's native format automatically.
 
-- 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`.
+```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
+```
 
-If a command still needs a human-only picker, it now exits with a plain-text hint that shows the matching non-interactive form.
+Write one `AGENTS.md`. It becomes `CLAUDE.md` for Claude Code, `GEMINI.md` for Gemini CLI, `.cursorrules` for Cursor.
 
 ---
 
-## Search sessions fast
-
-Interactive terminals now get a live-search picker for sessions:
+## Run any agent
 
 ```bash
-agents sessions view
-agents sessions --agent codex
-agents sessions --project agents-cli
-agents sessions view --agent gemini "session discovery"
+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"
 ```
 
-What you can type into the picker:
-
-- Session ID or short ID
-- Prompt text / topic text
-- Project name
-- Account email
-- Agent name or version
+Each resolves to the project-pinned version with skills, MCP servers, and permissions already synced.
 
-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`.
+### Rate-limited? Keep working.
 
-Use `agents sessions view <id>` in non-interactive shells when you already know the session you want.
-
----
+```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
+```
 
-## Pin agent versions per project
+### Multiple accounts? Spread the load.
 
 ```bash
-agents add claude@2.0.0             # Install specific version
-agents use claude@2.0.0 -p          # Pin to this project
+# Picks the signed-in account you haven't used recently.
+agents run claude "summarize recent commits" --rotate
 ```
 
-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.
+`--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.
 
-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.
+### Chain agents
 
----
+```bash
+agents run claude "Review PRs merged this week, summarize risks" \
+  | agents run codex "Write regression tests for the top 3 risks"
+```
 
-## Install skills, MCP servers, and commands once -- every agent gets them
+Supports plan (read-only) and edit modes, effort levels, JSON output for scripting, and timeout limits.
 
-### Skills
+---
 
-Skills are reusable knowledge packs -- rules, patterns, and expertise that make your agents better at specific tasks. Install once, available everywhere.
+## Sessions across agents
 
 ```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
-```
+# Where was that auth conversation? Search Claude Code, Codex, Gemini CLI, OpenCode at once.
+agents sessions "auth middleware"
 
-A skill is a directory with a `SKILL.md` and optional rule files:
+# 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
 ```
-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.
+Interactive picker when you're in a terminal. Structured output (`--json`, `--markdown`, filtered by role or turn count) when piped.
+
+---
 
-### Install MCP servers everywhere at once
+## Run open models through Claude Code
 
 ```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
+# 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"
 ```
 
-No more running `claude mcp add`, then `codex mcp add`, then editing Gemini's config file.
-
-### Manage slash commands
-
-```bash
-agents commands add gh:yourname/commands    # Install from repo
-agents commands list                        # See all commands
-agents commands view review-pr              # View command content
+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
 ```
 
-Commands are markdown files with a description. The CLI handles format conversion automatically -- markdown for Claude/Gemini/Cursor, TOML for Codex.
+Profile YAML has no secrets -- safe to `agents push` to a shared repo. `agents profiles presets` lists the full catalog.
+
+---
 
-### Sync your entire setup
+## Teams
 
 ```bash
-agents push                       # Snapshot your config to git
-agents pull                       # Restore on any machine
-```
+agents teams create auth-feature
 
-`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.
+# 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 fork                       # Fork the default repo to your GitHub
-agents pull --upstream             # Merge updates from upstream
+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
 ```
 
-### Interactive PTY sessions
+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`.
+
+---
 
-Give your agents the ability to interact with full-screen terminal programs -- REPLs, TUIs, interactive installers, anything that needs a real terminal.
+## Secrets
 
 ```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
+# API keys in Keychain, not in .env files.
+agents secrets add prod-stripe
+agents secrets set prod-stripe STRIPE_SECRET_KEY     # Prompts, stores in Keychain
+agents secrets set 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
 ```
 
-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.
+Merge order: profile env < `--secrets` < `--env K=V`. A missing keychain item aborts before the child starts.
+
+---
 
-### 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"
 
-agents daemon start                    # Start the scheduler
-agents routines list                   # See all jobs
-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 pull
 
-agents permissions list           # Show permission sets
-agents permissions add ./perms    # Install permission groups
-```
+# Installs CLIs, registers MCP servers, syncs skills/commands/rules/hooks,
+# sets up shims, configures defaults. Done.
 
-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).
+agents push     # Snapshot your config to git
+```
 
 ---
 
-## Quick Reference
+## Compatibility
 
-```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
-agents fork                       # Fork to your GitHub
-
-# 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 exec <agent> <prompt>      # Run agent
-agents sessions view <id>         # 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
-agents routines list              # Show all jobs
-agents daemon start               # Start scheduler
-
-# 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
-```
+| Agent | Versions | MCP | Commands | Skills | Rules | Hooks | Permissions | Routines | Teams |
+|-------|----------|-----|----------|--------|-------|-------|-------------|----------|-------|
+| Claude Code | yes | yes | yes | yes | CLAUDE.md | yes | yes | yes | yes |
+| Codex CLI | yes | yes | yes | yes | AGENTS.md | yes | yes | yes | yes |
+| Gemini CLI | 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 | -- | -- | -- |
 
----
+## FAQ
 
-## Skill Format
+### Why use `agents` instead of `claude` / `codex` / `gemini` directly?
 
-Create a `SKILL.md` with YAML frontmatter:
+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`.
 
-```markdown
----
-name: python-expert
-description: Python code analysis, type hints, and testing patterns
-author: Your Name
-version: 1.0.0
-keywords: [python, testing, types]
----
+### Is this like `nvm` / `mise` / `asdf` for AI agents?
 
-# Python Expert
+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.
 
-High-level description of what this skill teaches your agents.
-```
+### Does it store my API keys or send telemetry?
 
-Add rule files in a `rules/` subdirectory -- each rule is a markdown file with specific guidance your agents follow during conversations.
+No. API keys come from your shell environment or each agent CLI's existing auth. No telemetry, no phone-home. All state lives in `~/.agents/`.
 
----
+### Which platforms?
 
-## Compatibility
+macOS and Linux. Windows via WSL works but isn't first-class yet.
+
+### Do I need Node.js?
+
+The installer tries Bun first (faster), falls back to npm. Node 18+ required at runtime.
 
-| Agent | Versions | MCP | Commands | Skills | Rules | Hooks | Permissions | Routines |
-|-------|----------|-----|----------|--------|-------|-------|-------------|----------|
-| Claude | yes | yes | yes | yes | CLAUDE.md | yes | yes | yes |
-| Codex | yes | yes | yes | yes | AGENTS.md | yes | yes | yes |
-| Gemini | yes | yes | yes | yes | GEMINI.md | yes | -- | yes |
-| Cursor | yes | yes | yes | yes | .cursorrules | -- | -- | -- |
-| OpenCode | yes | yes | yes | yes | AGENTS.md | yes | yes | -- |
-| OpenClaw | yes | yes | -- | yes | workspace/AGENTS.md | yes | -- | -- |
+### Can I use it in CI?
 
-## How It Compares
+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.
+
+### 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, memory 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
+
+```bash
+git clone https://github.com/phnx-labs/agents-cli
+cd agents-cli
+bun install && bun run build && bun test
+```
 
-See [docs/04-landscape.md](docs/04-landscape.md) for a detailed comparison with other tools in the ecosystem -- Rivet, Agentloom, mise, skills.sh, cass, Microsoft APM, and more.
+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
+MIT -- see [LICENSE](./LICENSE).