agi-cli

<p align="center"> <img src="assets/logo.png" alt="agi-cli" width="120" /> </p> <h1 align="center">agi-cli</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/agi-cli"><img src="https://img.shields.io/badge/github-phnx--labs%2Fagi--cli-blue?style=flat-square" alt="github" /></a> </p> **A framework for running a distributed agent factory.** Dispatch Claude, Codex, Antigravity, Grok, and more across your own machines, in parallel, on your existing subscriptions. Measure every run with `agents insights` (latency lives at `agents insights perf`), fold what you learn back into `AGENTS.md` and skills, then put the loop on a schedule with cron. Spawn parallel teams in isolated terminals or dispatch to the cloud for a PR. Watch live state across the fleet, nudge stalled runs, and message agents mid-flight. Store secrets behind Touch ID, drive real browsers and Electron apps, and steer the whole fleet from a menu bar — all from one CLI. <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> &nbsp;&nbsp;&nbsp;&nbsp; <a href="https://x.ai" title="Grok Build (xAI)"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/harnesses/grok.png"><img src="assets/harnesses/grok-light.png" height="32" alt="Grok Build" /></picture></a> &nbsp;&nbsp;&nbsp;&nbsp; <a href="https://factory.ai" title="Factory AI Droid"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/harnesses/droid.png"><img src="assets/harnesses/droid-light.png" height="32" alt="Factory AI Droid" /></picture></a> &nbsp;&nbsp;&nbsp;&nbsp; <a href="https://dev.meta.ai/docs/muse-code" title="Meta Muse Code"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/harnesses/muse.svg"><img src="assets/harnesses/muse-light.svg" height="32" alt="Meta Muse Code" /></picture></a> &nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp; <a href="https://docs.warp.dev/reference/cli" title="Warp Agent CLI (Oz)"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/harnesses/warp.svg"><img src="assets/harnesses/warp-light.svg" height="32" alt="Warp Agent CLI" /></picture></a> </p> <p align="center"> <img src="assets/demos/hero.gif" alt="agents CLI: sessions across every agent and project, chaining agents in a Unix pipeline, dispatching to the cloud, and one team spread across machines" width="860" /> </p> <p align="center"><a href="https://agi-cli.sh/demo.mp4">Watch the full 56-second demo</a></p> <p align="center"><b>Command reference:</b> <a href="cli/docs/command-index.md">every <code>agents</code> command</a> · <a href="cli/docs/command-reference.html">searchable HTML page</a></p> ## Quickstart ```bash npm install -g @phnx-labs/agents-cli # or: curl -fsSL agi-cli.sh | sh agents setup # first-time setup, or re-open the capability hub agents setup status # readiness for browser, computer, fleet, and more agents setup tools # install/upgrade the standalone sessions, browser, secrets, computer, term CLIs to their pins agents run claude "explain this repo" # run any agent on your existing subscription ``` Everything here — and every other command in this README — is free and needs no account; the optional `agents auth login` unlocks the hosted surfaces — [team spaces](#sign-in) and owner notifications. `agents setup` is interactive and idempotent -- safe to re-run on any machine. Once core setup exists, it opens a status-aware menu for browser, computer, secrets, term, fleet, and device preferences; each choice delegates to the same wizard available under `agents setup <capability>`. In CI or another non-TTY, bare setup prints the checklist without prompting. The `agi-cli.sh` one-liner installs this same canonical `@phnx-labs/agents-cli` package. Prefer bun? `bun install -g @phnx-labs/agents-cli` works too. The command surface teaches setup through `agents setup` and group-level `--help`. The durable system model starts at [`cli/docs/README.md`](cli/docs/README.md). **What `agents setup` installs, and what auto-updates.** Setup clones a small public **system repo** (`phnx-labs/.agents-system`) into `~/.agents/.system/`. It ships the default resources — including **hooks**, which run as shell commands on tool events — and its checkout **fast-forwards from its origin** when you run `agents use` (and, only if you opt in with `AGENTS_AUTO_PULL=1`, in the background). Two safeguards bound that: the pull is `merge --ff-only` (it can never rewrite your local history), and it is **verified against the expected origin** — a checkout whose `origin` is not the canonical system repo (or the exact repo you named in `AGENTS_SYSTEM_REPO`) is refused, never pulled, so a repointed remote cannot slip hook code onto your machine. To pin or opt out: set `AGENTS_SYSTEM_REPO=gh:you/your-fork` to track your own audited copy, run `agents setup --no-system-repo` to skip the clone entirely, or check out a specific tag in `~/.agents/.system/` (a fast-forward only advances a moving branch, so a detached tag stays put). **Learn (concepts):** [Loop + graph engineering](https://agi-cli.sh/learn/loop-and-graph-engineering) · [Teams as graph engineering](https://agi-cli.sh/learn/teams-graph-engineering) · [Sessions · index + cross-device](https://agi-cli.sh/learn/sessions-index) · [Distributed fleet execution](https://agi-cli.sh/learn/distributed-fleet). Also: [harness engineering](https://agi-cli.sh/learn/harness-engineering) · [visual longform](https://share.agents-cli.sh/muqsitnawaz/agents-loop-and-graph-engineering). Already installed? `agents upgrade` updates agi-cli itself to the latest version (`agents upgrade 1.2.3` for a specific version or dist-tag, `-y` to skip the confirm prompt). The command is `upgrade` on every platform -- do not reach for `agents update`, which updates an installed **agent harness**, not agi-cli. Source: [github.com/phnx-labs/agi-cli](https://github.com/phnx-labs/agi-cli) Also available as `ag` -- all commands work with both `agents` and `ag`. - [Factory loop](#factory-loop) - [One config, every agent](#one-config-every-agent) - [Run any agent](#run-any-agent) - [Sessions across agents](#sessions-across-agents) - [Control the fleet](#control-the-fleet) - [Sync the fleet](#sync-the-fleet) - [Pin versions per project](#pin-versions-per-project) - [Run open models through Claude Code](#run-open-models-through-claude-code-experimental) - [Run on your own machines](#run-on-your-own-machines) - [Teams](#teams) - [Cloud](#cloud) - [Workflows](#workflows) - [Plugins](#plugins) - [Make it yours](#make-it-yours) - [Browser](#browser) - [Sign in](#sign-in) - [Accounts](#accounts) - [Secrets](#secrets) - [Daemon](#daemon) - [Share](#share) - [PTY](#pty) - [Portable setup](#portable-setup) - [Menu bar](#menu-bar) - [Private skills](#private-skills) - [Security & Privacy](#security--privacy) - [Compatibility](#compatibility) - [FAQ](#faq) --- ## Factory loop The same loop whether it's one agent on your laptop or a fleet across a dozen machines: dispatch work, measure what happened, fold the lesson back into the harness, then put it on a schedule. ```bash # Dispatch a team across the fleet -- each teammate in its own worktree agents teams create checkout --devices yosemite-s0,yosemite-s1 agents teams add checkout claude "Owns: app/payments/*" --name payments agents teams add checkout codex "Write tests for the new code" --name qa --after payments agents teams start checkout --watch # Measure what happened -- latency, friction, dead-weight skills agents insights perf commands --days 7 # slowest CLI entrypoints agents insights --since 30d # friction, harness comparison, ranked actions # Fold the lesson back into the harness -- every agent picks it up next run agents rules add ~/lessons/payments-review.md --agents claude agents skills add ~/skills/payments-review --agents claude # Put it on a schedule so it runs itself (crontab -e) # 0 2 * * * agents run claude "Audit payments/* for regressions" --mode auto # Check the fleet this loop runs on, AGI Menu included agents doctor ``` `agents insights perf` reads a disposable warehouse at `~/.agents/.cache/perf/perf.db` -- hook, command, and run timing rollups, deletable any time. `agents insights` is deterministic and offline: it caches per-session facets, compares harnesses, and ranks actions by evidence count -- no model call unless you pass `--narrative`. Schedule any of this with OS cron, a systemd timer, or launchd calling `agents run`; the menu bar is the always-on control surface for the fleet these commands drive ([Menu bar](#menu-bar)). --- ## One config, every agent ```bash # Set up the Notion MCP server once. agents mcp add notion uvx notion-mcp --agents claude,codex,antigravity,cursor # It's now registered with Claude Code, Codex, Antigravity, 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 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 -> per-agent instruction files agents permissions add ./perms # Permissions -> auto-converted per agent ``` Write one `AGENTS.md`. It becomes `CLAUDE.md` for Claude Code, `AGENTS.md` for Antigravity, and `.cursorrules` for Cursor. --- ## Run any agent <p align="center"> <img src="assets/run-agent.svg" alt="agents run: one command runs any harness (claude/codex/antigravity) against the project-pinned version, with an automatic rate-limit fallback chain." width="100%" /> </p> ```bash agents run claude "Find all auth vulnerabilities in src/" agents run codex "Fix the issues Claude found" agents run antigravity "Write tests for the fixed code" ``` Each resolves to the project-pinned version with skills, MCP servers, and permissions already synced. Single-typo names auto-correct across every command — `agents view cladue` resolves to `claude`, `agents add codx@latest` to `codex`. `agents run claude "task" --lease` reuses one shared warm crabbox pool across repositories by default. Concurrent runs share the box but execute in isolated `~/workspaces/<repo>-<run>` directories with separate agent homes and credential files. Add `leaseProfile: private-hot-box` to `.crabbox.yaml` only when a repo intentionally needs a dedicated warm pool; cross-repo reuse trades re-sync latency for lower idle-compute cost. ### Rate-limited? Keep working. ```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,antigravity ``` ### Multiple accounts? Spread the load. ```bash # Picks the signed-in account you haven't used recently. agents run claude "summarize recent commits" --strategy balanced # Or choose one account/version interactively for only this run (# = account picker). agents run claude# agents run codex# "review this branch" agents run claude# --device auto # pick the device, then choose there agents run claude# --device yosemite-s0 # choose from one device's accounts # @ picks the device instead; #@ asks both (account first, then device). agents run claude@ # pick the device for this run agents run claude#@ # pick the account, then the device ``` `--strategy balanced` spreads work across available versions of the same agent -- useful when you have multiple accounts and want to avoid burning through one. It picks only subscription logins and setup-tokens; an API-key account (OpenRouter, an Anthropic or OpenAI key) bills per token, so it runs only when you name it with `--account`. When a Claude run reports a session limit, agents-cli records the stated reset time, shows `session-limited` in `agents view`, and excludes that account until the reset. When every account is rate-limited, the run exits nonzero naming each excluded account and the earliest window reset (use `--strategy pinned` to force a rate-limited default) -- it never launches into an exhausted account. A logged-out default is never forced: unpinned dispatch picks a signed-in version on the execution device instead of dying on a credential-less default home. ### Don't care which harness? `agents run auto` ```bash # Picks the host (14d usage affinity), the harness (installed CLIs weighted by # best-account headroom), and the account (balanced) -- all three layers. agents run auto "summarize recent commits" agents run auto --device yosemite-s0 "fix the flaky test" # pin the host layer ``` `run auto` excludes any harness whose accounts are all rate-limited or signed out, and exits nonzero with the earliest reset time when nothing anywhere is healthy. A trailing `@` opens an account picker before either an interactive or prompt-based run. Each installed version shows its account identity, exact version, login state, plan, and every available session, weekly, or monthly limit. Logged-out, rate-limited, and out-of-credit accounts remain visible with the reason they cannot be selected; signed-in accounts whose provider does not expose quota data stay selectable and say `limits unavailable`. The choice pins only that run and does not change your default version. Account selection is available for Claude, Codex, Gemini, Cursor, Antigravity, Grok, Kimi, Droid, and OpenCode. It requires a terminal and cannot be combined with `--resume`, `--strategy`/`--balanced`, `--lease`, or a warm-box lease. Device routing is resolved first, then the picker is populated from the selected device. Profiles and workflows must use their concrete host agent instead. ### Chain agents ```bash agents run claude "Review PRs merged this week, summarize risks" \ | agents run codex "Write regression tests for the top 3 risks" ``` Supports plan (read-only), edit, auto, and skip modes, effort levels, JSON output for scripting, and timeout limits. ### What does `--mode skip` actually do? Treat `skip` as a last-resort escape hatch. In direct-exec runs (without `--acp`), agi-cli forwards the harness's native no-prompt flag; it does not add another safety layer. Prefer `auto` where it adds a safer automatic policy (smart classifier on Claude/Copilot, Grok's native auto mode, never-prompt over a sandbox on Codex, native high-auto mode on Droid, or interactive Kimi), or `edit` everywhere else. For headless Kimi, `edit`, `auto`, and `skip` all use the same already-auto-approved `-p` behavior, so prefer `edit` rather than signaling a blanket bypass. Harnesses without a native bypass flag reject direct-exec `skip`. | Harness | Direct-exec `--mode skip` becomes | |---|---| | Claude Code | `--dangerously-skip-permissions` | | Codex | `--dangerously-bypass-approvals-and-sandbox` (equivalent to `--yolo`) | | Gemini | `--yolo` | | Cursor | `-f` | | OpenClaw | `--mode full` | | GitHub Copilot | `--allow-all` (alias: `--yolo`) | | Antigravity | `--dangerously-skip-permissions` | | Grok | `--always-approve` | | Kimi | `--yolo` interactively; no extra flag in headless `-p` runs, which already auto-approve | | Droid | `--skip-permissions-unsafe` | With `--acp`, these native flags are not used. agi-cli instead grants `skip` permission requests at the ACP protocol layer: it selects `allow_always` when offered, otherwise the first permission option offered by the server. The same last-resort warning applies. Codex has three managed permission profiles rather than a smart classifier. `edit` and `auto` share one sandbox — the workspace, `~/.agents`, and regenerable toolchain caches are writable, and network access is enabled — and differ only in approvals: `edit` requests them on demand, while `auto` never prompts, so a sandbox-denied command fails and the agent works around it instead of stopping on a dialog nobody is watching. When `--mode` is omitted for Codex, `edit` is used. An explicit `--mode plan` keeps the filesystem read-only while leaving network access on. `agents run codex --mode skip` is different: it bypasses approvals **and** removes the sandbox. `full` remains an alias for `skip`, but new scripts should use the explicit `skip` name. ### 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 ``` `--acp` routes through the [Agent Client Protocol](https://github.com/zed-industries/agent-client-protocol) so you get a unified event stream -- `agent_message_chunk`, `tool_call`, `plan_update`, `stop_reason` -- instead of writing a parser per CLI. File writes and shell commands flow through agi-cli, which means `--mode plan` becomes a real sandbox: the write RPC is denied, not just unused. ACP adapters are documented for claude, codex, cursor, opencode, openclaw, and grok. Other harnesses keep running on the direct-exec path. --- ## Sessions across agents <p align="center"> <img src="assets/sessions.svg" alt="sessions: search transcripts across Claude, Codex, legacy Gemini, and OpenCode at once, plus a live panel showing each running session's state (working / waiting / idle)." width="100%" /> </p> When you run multiple agents, conversations scatter across tools. Session search brings them together. Searching and reading transcripts is the standalone **`sessions` CLI** (`@phnx-labs/sessions-cli`, installed by `agents setup tools`); agents-cli keeps the index it reads current. ```bash # Where was that auth conversation? Search Claude Code, Codex, legacy Gemini, OpenCode at once. sessions "auth middleware" # Filter by agent, project, or time window sessions --agent codex --since 7d sessions --project my-app # Read a full conversation sessions a1b2c3d4 --markdown # Render a shareable, redacted Markdown transcript with the session preview on top sessions render a1b2c3d4 -o session.md # Or publish it as a link in one step (unlisted + redacted by default) sessions share a1b2c3d4 # Visualize a session as a trajectory -- tool-call waterfall, timing, stalls, errors agents trace a1b2c3d4 # opens the HTML (a person at a terminal) agents trace a1b2c3d4 --text --errors-only # compact text an agent reads in-context agents trace a1b2c3d4 --json # the versioned sessions-trace envelope # Just the last 3 turns, user messages only sessions a1b2c3d4 --last 3 --include user # Search indexed tool calls (same index) sessions --include tools --query 'program:git input:merge' --query 'program:gh output:CONFLICT' --json sessions --include tools --query 'program:git' --count --host box1,box2 --json # Populate historical tool rows once on each device agents daemon index backfill tools --fleet # Which skills/commands you actually invoke -- and which installed ones are dead weight agents insights resources agents insights resources --zero # only the never-invoked (dead weight) agents daemon index backfill resources # fold historical sessions into the usage index # Friction, owner corrections, repeated recipes, and ranked actions across harnesses agents insights --since 30d agents insights --agent claude --agent codex --json ``` `agents insights` is deterministic and offline by default. It caches per-session facets, compares harnesses, and emits an actions table with evidence counts plus shortened sample session ids. `--narrative` is opt-in and receives aggregates only, never raw transcripts. Interactive picker when you're in a terminal. Structured output (`--json`, `--markdown`, filtered by role or turn count) when piped. Backed by a SQLite + FTS5 index at `~/.agents/.history/sessions/sessions.db` with incremental scanning -- warm reads in ~100ms. Tool-call evidence is redacted and bounded before it is cached. agents writes the tool index (`agents daemon index backfill tools` performs the one-time historical parse, while normal incremental scans index new and changed sessions); the standalone `sessions --include tools` reads it, including `--count` over the ordered static Bash program sites. This uses relational SQLite rows and literal FTS5 only, with no embeddings, vector database, or model calls. External tools can consume `--json` output as a programmatic observability layer; see [docs/sessions.md](cli/docs/sessions.md) for the schemas and [docs/observability.md](cli/docs/observability.md) for the consumption patterns. ### Live state, and catching up fast Search is the past tense. `agents ps` is the present -- it infers what each running session is *doing right now* from the tail of its transcript, on this machine and every reachable device. ```bash agents ps # the live roster (opens the picker on a TTY) agents ps --json --local # this machine only, machine-readable agents ps --json -D box-a # one peer, over SSH agents ps --status waiting # only agents waiting on you (exit 1 if any) agents ps --bookmarks # only bookmarked sessions agents ps stop|focus|detach|migrate <id> # act on one running agent agents ps migrations # where migrated sessions went agents ps --status working # actively producing work (fleet-wide) agents ps --status idle # stopped between turns agents ps --status orphaned # agent outlived its terminal client agents ps focus a1b2c3d4 # jump back into one — attach in place, or recover agents ps focus ag-claude-a1b2c3d4 # or by its tmux alias ``` On a terminal, a bare `sessions` opens the **interactive session browser** — one filter you drive with single keys: | key | filters by | flag it mirrors | |---|---|---| | `s` | search text (title + full text) | positional query | | `a` | agent (cycles) | `-a` | | `d` | device (cycles) | `--machine` | | `t` | one team | `--in-team` | | `c` | team-spawned sessions | `--teams` | | `b` | bookmarks only | `--bookmarks` | | `*` | bookmark / unbookmark the highlighted session | `sessions bookmark <id>` | | `p` | this repo ↔ all dirs | `--all` | | `w` | time window | `--since` | | `tab` | toggle the preview pane | — | | `⏎` | resume | `agents run <agent> --resume <id>` | | `y` | copy the equivalent `sessions …` command | — | **Bookmark the sessions you keep coming back to.** `*` marks the highlighted row (a `★` shows in the listing), `b` narrows to bookmarks, and `sessions bookmark <id>` / `sessions --bookmarks` do the same outside a TTY. Bookmarks live in `~/.agents/.history/bookmarks.json` keyed by session id, so they survive a reindex of the session cache. They're per-machine — session sync carries transcripts, not this file. **A session that lost its host says so.** When an editor window or an SSH connection goes down hard, the agent it owned used to simply disappear from the live roster; when an agent outlived its window in tmux, it reported a plain `idle`. Both now carry their own status: `✗ crashed` (the host went down and took the agent with it) and `◍ orphan` (still alive, but no client is attached — nothing is showing it). Read from tmux's attached-client count and the editor window's registry heartbeat, so a deliberate `agents ps detach` is never mistaken for one, and a session that is still *working* headlessly is left alone. Filters **stack** (they AND together), the active set shows in the header, and the highlighted row **previews beside the list** (`tab` toggles it) — prompt, activity, last response, plus a links line where the worked-on ticket and the PR the session opened are **clickable** (OSC 8 hyperlinks: the ticket jumps to Linear, the `PR#` to GitHub, in terminals that support them). The Linear workspace is resolved from `LINEAR_WORKSPACE` or the linear-cli config, so tickets stay plain text when it's unknown. Because the filters map to flags, the view you build by hand is a real command: press `y` to get the exact `sessions …` line — explore interactively, hand the line to an agent. Piped output, `--json`, or `--no-interactive` keep the plain listing for scripts. Peek without opening the browser with `sessions preview <uuid-or-8-char-id>` (`--json` for its digest). | before — preview hidden | after — preview open + clickable links | | --- | --- | |  |  | Each live session resolves to `working`, `waiting_input` (with why -- a question, a plan review, or a permission prompt), `idle`, or a lifecycle state such as `orphaned`, `crashed`, `closed`, `abandoned`, `queued`, or `unknown`. Narrow `agents ps` to one with `--status <state>`. The fleet fan-out is already the default; `--local` opts out. Rows also carry badges for the PR, worktree, and ticket. `agents ps focus [selector]` accepts agent/version, device, time, team, project, skill/plugin, bookmark, and live-state filters (`--working`, `--idle`, `--waiting`, `--orphan`, `--crashed`, `--closed`, `--abandoned`, `--queued`, `--unknown`). A unique id or `ag-<agent>-<shortid>` tmux alias resolves directly; an agent/version or text selector always opens the preview picker. Immediately before attach it checks the tmux pane process: a living pane is joined in place, while a dead/missing pane enters recovery instead of showing tmux's `Pane is dead` screen. Landing on a session cold? `sessions preview <id>` prints a catch-up card: an inferred title, what was asked, the files changed, failures, a histogram of which tools did the work, and the latest response -- the signals to reload a task in seconds. Sharing a session uses `sessions render <id> -o session.md`, not the raw harness JSONL. The document starts with that same preview, then presents user and assistant turns, fenced commands, structured tool arguments, and bounded tool output. Credential-shaped values and local home paths are redacted by default; `--no-redact` is for local-only inspection. `sessions share <id>` goes one step further and publishes that document as a self-contained web page through the standalone `artifacts` CLI, printing the link. Secrets and emails are masked before the page is written. The slug is `session-<shortId>`, so re-sharing one session updates one URL. The agents-cli spelling, `sessions share <id>`, publishes the page **unlisted** unless you pass `--public` (with `--label <text>` as its gallery title): a transcript carries file paths, command output, and error text that a plan does not, so it stays out of your public gallery by default. ### Publish CleanShot recordings The opt-in recordings service turns finished CleanShot exports into organization-only artifacts. It watches on the daemon's schedule, waits until the file size has stopped changing for 10 seconds, creates a temporary 1080p/30fps H.264 copy, and leaves the original untouched. Enabling the watcher establishes a fresh baseline, so existing files are not bulk-published; use `upload` to publish an older file explicitly: ```bash agents recordings watch # use CleanShot's macOS exportPath agents recordings watch --dir ~/Movies/Demos # or choose a folder agents recordings list # queued, failed, and published rows agents recordings upload ./demo.mov # one file through the same pipeline agents recordings unwatch ``` Install `ffmpeg` and `@phnx-labs/artifacts-cli`, then sign in to `artifacts` with an organization email. Every publish uses `--visibility org --expire never`; public inbox identities are refused rather than turning a team recording into a personal artifact. CleanShot re-exports such as `… AM 3.mp4` replace the earlier artifact at the same slug. The restart-safe ledger is `~/.agents/recordings/ledger.json`. See [the recordings guide](cli/docs/recordings.md) for the data flow and failure behavior. ### Back up sessions off-box Signed-in Phoenix users can back sessions up without creating a Cloudflare bucket or an `r2.backups` secrets bundle: ```bash sessions export --since 30d --to-r2 sessions import --from-r2 --dry-run sessions import --from-r2 ``` The managed path encrypts every transcript body locally with AES-256-GCM before upload. Its per-account key is escrowed behind the same Phoenix bearer so another signed-in device can restore with zero setup. This protects transcript contents from a raw storage-bucket read, but it is not zero-knowledge against Phoenix because Phoenix-operated infrastructure stores the recovery key. Use `--byo` with your own `r2.backups` bundle and `R2_SYNC_ENC_KEY` when Phoenix must never possess the key: ```bash sessions export --since 30d --to-r2 --byo sessions import --from-r2 --byo ``` Both targets are on-demand backups only; neither enables background session sync. ### Resume anywhere — and stay resumed Omit the session ID to choose from an interactive history picker with descriptions and conversation previews. These commands use the same picker and account filter: ```bash ag run claude --resume ag run claude#work --resume ``` Resume restores the conversation's account, model, mode and working directory with the currently installed harness. Updating that binary does not select a different account. If only archived context remains, the CLI asks before starting a new conversation from it; a missing transcript fails before launching an agent. Pick up any past conversation and drop it back into a terminal: ```bash agents ps focus # multi-select; each opens as a tab in this terminal agents ps focus "auth middleware" # pre-filter the pool, then choose agents ps focus --device zion # pick from one machine's live sessions agents ps focus 019fd0c8-b3e9-77a2-a1a4-444698c4d897 # original harness/version/device/mode agents run auto --resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897 # scripted continue; adapts if its account is unavailable ``` `agents run <agent> --resume` with no id opens a picker and reopens the selected sessions as tabs in whatever terminal you're in -- auto-detected across iTerm, Ghostty, tmux, and the VSCodium agent-terminal. `agents run auto --resume <id>` resumes one session without requiring you to name its harness: exact IDs take a local SQLite fast path, then resolve fleet-wide and recover on the source device. If the origin version is installed, signed in, healthy, and still owns the indexed transcript, its isolated home performs native resume. Claude launches that native resume from the original project directory recorded before the first turn, so its `projects/<cwd-key>` lookup reaches the conversation even when the session later changed directories. When that origin login is usage-limited but the home still owns the transcript, resume stays native and rotates to a healthy injectable provider account of the **same harness**. `/continue <id>` is the last-resort fallback — a signed-out, revoked, trashed, backup-only, or same-number-reinstalled origin, or a limited origin whose transcript is no longer in that home — and still authenticates as a healthy same-harness account (injecting a provider credential when that is the pick, so it never launches the exhausted native login). It never native-resumes from a different isolated home. Back them with **tmux** (`tmux.enabled`) and the runs turn durable: detach, close your editor, reboot the GUI -- `agents ps focus <id>` reattaches the still-running session. ### Send an agent to the background — and bring it back Running 30 agents and drowning in terminal tabs? `agents ps detach <id>` stops a session's interactive process and keeps it working **headless** in the background -- it drives its task to done unattended, no tab, lower cost. `agents ps focus <id>` brings it back through the same origin-device recovery decision: native resume in the owned account home, or an explicitly chosen same-harness `/continue` replay when native context is unavailable. ``` agents ps detach a1b2c3d4 # go headless in the background, keep working agents ps focus a1b2c3d4 # bring it back interactively, right here ``` Both are agent-agnostic -- they route through the same `agents run <agent> --resume` path (native resume for Claude/Codex, `/continue` replay for the rest). `agents ps` shows each session's **owner** (the human who launched it, resolved from the tailnet identity, or `-` for an unresolved local run) and its `presence` -- `attached` (you're watching it), `background` (running headless), or `parked` (its background run finished) -- so the menu bar and AGI EXT show who is running what, and where. In AGI EXT, **Agents: Detach** (`Cmd/Ctrl+K B`) and **Agents: Attach** (`Cmd/Ctrl+K A`) do the same over the focused terminal. --- ## Control the fleet Running agents aren't fire-and-forget. Steer them mid-run without opening their terminals. <p align="center"> <img src="assets/fleet-control.svg" alt="agents ps infers live state (working, waiting, idle); feed answer replies to an open ask; message reaches a running agent at its next tool call" width="100%" /> </p> ### Message a running agent ```bash # Queued in the agent's mailbox, read at its next tool call — no restart, no lost context. agents send --channel mailbox --to <session-id> --text "also cover the null case" --from orchestrator ``` The `mailbox` channel of `agents send` queues a note for a running agent by session id, and the text lands at its next tool call. A cloud task takes `agents cloud message <id> <text>`. To type straight into an agent's terminal instead -- a "continue" for one that stalled at a prompt -- use the `session` channel of `agents send`. The id is anything `agents ps` shows (session id or prefix, the `<shortid>` of an `ag-<agent>-<shortid>` tmux name, or a `%pane`); add `--device <name>` for a session on another box. ```bash agents send --channel session --to 4b2f1a9c --text "continue" ``` ### See every open block ```bash agents feed # grouped by outcome (ticket/PR/worktree) across the fleet agents feed --flat # one row per agent (legacy) agents feed --device mac-mini # scope the view to one or more hosts agents feed --local # skip the SSH fan-out agents feed --json # blocks stamped with their outcome key agents feed watch --json # versioned agents + attention + activity NDJSON agents feed answer <key> --choice 0 # first answer wins; route over the recorded reply rail agents feed post --title "Halfway done" "CI green, watching merge" # title + body ``` Important posts, blocks and `agents send --to owner` reach you through your account once you run `agents auth login`: email, Slack and iMessage per the preferences in the console Settings page, with dedup applied there. Workers get a scoped device token from your signed-in laptop automatically. rush/api sends the iMessages from Rush's own number to the phone number you confirmed in Settings, so no Mac is involved. Ordinary milestone posts remain record-only unless configured. An optional **per-session summarizer** (off by default) adds a daemon-computed `goal`, progress `checkpoints`, and a detailed `summaryChecklist` to each session row on the `feed watch` / `sessions watch` stream. It never runs on a request path — the model call lives in a background daemon service, cached per transcript so it never recomputes on unchanged bytes. Turn it on with a local model endpoint: ```bash agents config set summarizer.enabled on agents config set summarizer.baseUrl http://localhost:11434 # Ollama / vLLM / LiteLLM agents config set summarizer.model qwen2.5:3b ``` Top-level questions and waiting notifications publish one atomic open-block record per session, including the mailbox id, host, runtime, and every answer option. The default view collapses agents under the **outcome** they serve (Linear ticket, PR, worktree slug, or Unassigned) so a 1,100-agent fleet reads as dozens of deliverables. Answered, resumed, and stopped blocks clear automatically; Task subagents are excluded. The rendered reply command uses the same mailbox id with `agents send --channel mailbox`, so the decision routes back to the agent that asked it. ### Talk to a project Lead ```bash agents lead ask --project rush -- what is running? # starts the warm Lead on first use agents lead ask --project rush --json -- put Claude on PHNX-4365 agents lead confirm c_0123456789abcdef # a stop the Lead held for you agents lead history --project rush --json agents lead status --json agents lead stop --project rush ``` The Lead is one long-lived headless Claude per project that dispatches and manages agents. It runs with isolated settings and can only call fixed-shape `agents lead tool` commands (roster, dispatch, start, send, stop, linear, remember). It cannot edit files, and a stop runs only through a confirm token. A per-project host keeps it warm across callers, so a follow-up turn skips the harness boot. `--json` streams the NDJSON events the AGI EXT and bubble clients render. Reference: [cli/docs/lead.md](cli/docs/lead.md). --- ## Sync the fleet <p align="center"> <img src="assets/fleet-sync.svg" alt="agents fleet apply: reconcile every device to one profile from agents.yaml — install missing agents and sync config. Native logins stay on the machine that minted them." width="100%" /> </p> One machine is set up the way you like it. Make every other machine match -- same agents installed, same config -- in one command. Native OAuth logins stay on the box that minted them; portable provider accounts move only via `agents accounts sync`. ```yaml # agents.yaml -- add a fleet: block fleet: devices: all # every online registered device (minus this one) defaults: agents: [claude@latest, codex@latest, antigravity@latest] sync: [user] # config scopes to reconcile login: sync # surface needs-login; never copies native OAuth ``` ```bash agents fleet apply --plan # device x dimension matrix; changes nothing agents fleet apply # reconcile the fleet (confirms first; -y to skip) agents fleet apply --device yosemite-s0 # scope to one device agents fleet apply --only agents,config # limit dimensions (agents, config, login) agents fleet apply --no-login # skip login propagation ``` `agents fleet apply` probes every target over the existing SSH transport, then reconciles it to the profile: installs missing agents, upgrades `agi-cli`, syncs the named config scopes, and **propagates logins** so a host signed in once seeds the fleet -- turning "6 hosts x 8 harnesses = 48 OAuth flows" into one. Portable credential files (claude, codex, grok, kimi, opencode, droid, antigravity) stream to each target over encrypted SSH stdin, never shell-interpolated, and land at `0600`. **Honest boundary:** macOS keychain-bound tokens (claude, antigravity on a Mac target) can't be extracted -- those surface as a one-time manual login, never faked. `--plan` / `--dry-run` shows the full matrix without touching anything. See [docs/fleet.md](cli/docs/fleet.md) for the manifest schema and reconcile semantics. --- ## Pin versions per project ```bash # 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 ``` This creates an `agents.yaml` at the project root: ```yaml # agents.yaml (commit this to your repo) agents: claude: "2.0.65" codex: "0.116.0" ``` Think `requirements.txt` for CLI coding agents, on steroids. A shim reads `agents.yaml` from the project root and routes `claude` / `codex` / `antigravity` / `grok` (and others) to the right version automatically. Each version gets its own isolated home -- switching backs up config and re-syncs resources. ```bash agents add claude # Install the one managed installation (taught form) agents add claude@2.0.65 # Pin that installation to a specific release (expert) agents add codex@latest # Latest published release agents view # See everything installed agents accounts add claude work # headed: login + worker credential + sync agents run claude#work ``` Multiple provider accounts to juggle? See [Accounts](#accounts) below. --- ## Run open models through Claude Code (experimental) > **Note:** Profiles are experimental, but available by default — no enable step needed. ```bash # Kimi K2.5 responding inside Claude Code's UI, tools, and skills. # No proxy server. No LiteLLM. One OpenRouter key, stored in Keychain. agents harness add kimi agents run kimi "refactor this file" ``` Built-in presets (all via OpenRouter, one shared key): | Preset | Model | Notes | |---|---|---| | `kimi` | Kimi K2.5 | #1 HumanEval. Reasoning -- interactive only. | | `minimax` | MiniMax M2.5 | #1 SWE-bench Verified. Reasoning. | | `glm` | GLM 5 | #1 Chatbot Arena (open-weight). | | `qwen` | Qwen3 Coder Next | Latest coding Qwen. Print-safe. | | `deepseek` | DeepSeek Chat V3 | Latest non-reasoning. Print-safe. | A profile swaps the model while keeping Claude Code as the agent runtime -- same UI, slash commands, skills, MCP tools. Under the hood: `ANTHROPIC_BASE_URL` + `ANTHROPIC_MODEL`, auth from Keychain at spawn time. Custom endpoints (Ollama, vLLM) work too -- drop a YAML in `~/.agents/profiles/`: ```yaml name: local-qwen host: { agent: claude } env: ANTHROPIC_BASE_URL: https://ollama.example.com 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 harness list` lists the full catalog. --- ## Run on your own machines <p align="center"> <img src="assets/hosts.svg" alt="agents devices: dispatch agents run and config commands to another machine over plain SSH (no daemon); the Tailscale fleet is auto-discovered." width="100%" /> </p> Dispatch any read-only or config command -- and `agents run` itself -- to another machine over SSH. No daemon. ```bash # Enroll a machine by hand (Tailscale nodes register with `agents devices sync`, below) agents devices add gpu-box me@gpu-box.example.com agents devices show gpu-box # the resolved profile: address, user, auth # Run there instead of locally agents run claude --device gpu-box "profile this build" # headless: follows live by default agents run claude --device gpu-box # no prompt → direct interactive TTY over SSH agents accounts sync work --device gpu-box # portable provider account only; native OAuth stays local agents run claude --device auto "…" # affinity-pick host from 14d usage (harness stays claude) agents run claude --device auto "…" # same — auto is a host value, not a harness name agents view kimi --device all # fan out across every registered device (grouped-by-OS roster) agents insights output --device all # per-device burn vs shipped output across the fleet agents view --device all --json # machine-readable fleet inventory agents devices ps # list dispatched runs + terminal status agents devices stop <id> # terminate a hung/detached run (alias: kill) agents events logs --device gpu-box # pick a dispatched run — concise summary by default agents events logs <id> --full # the full raw transcript / stdout (token-heavy) agents events logs <id> -f # re-attach to a running one and follow agents view claude --device gpu-box # inspect the remote install agents sync --device gpu-box # make the remote machine current agents doctor claude # diagnose every installed claude version agents doctor claude@latest # diagnose only the newest installed version agents doctor claude@oldest # diagnose only the oldest installed version agents doctor claude@pinned # diagnose the global-default (pinned) version agents doctor claude@all # diagnose all versions, including isolated copies agents doctor claude@latest --device mac-mini # diagnose newest claude on mac-mini agents doctor --devices # readiness matrix for every registered device agents doctor --devices --json # machine-readable fleet readiness agents doctor --device mac-mini # same matrix, scoped to one device agents fleet status # online/offline rollup + NEEDS ATTENTION + OS-grouped rows (cache-first) agents fleet status --verbose # full per-device auth/CLI/sync/version grid agents fleet status --live # force a live resource probe (alias of --refresh) agents fleet status --json --strict # scriptable fleet health gate agents fleet worktrees # held agent worktrees by bucket: stranded (unmerged) · dirty · undeterminable agents fleet worktrees --fleet # aggregate the held set across every online device agents fleet worktrees --push # publish stranded on-no-remote branches (recovers work; never deletes) agents devices harnesses # per device: agent@version · account · signed · quota · ready agents devices accounts # same, one row per account (which harnesses share it) agents devices harnesses --agents claude,codex --json # scoped, machine-readable agents doctor --check --devices # CI drift gate across every registered device # Your Tailscale fleet, auto-discovered agents devices sync # ingest `tailscale status` agents devices ignore ipad # sync the dismissal via agents.yaml fleet.discovery agents repo push user # carry device decisions to the other machines agents repo pull user # pull and reconcile them into this machine's registry agents devices list # spec (cores/RAM/disk) + load/mem/disk + headroom + role + description agents devices list --live # force a live probe of every device (alias of --refresh) agents devices list --full # add per-device free/total RAM detail agents devices list --no-stats # instant: names/addresses only, skip the probe agents devices describe mac-mini "signing + notarize box" # one-line purpose, synced + shown in the list agents devices ignored # dismissed nodes — when, and which machine dismissed them agents devices config zion interactive.host zion # the device agents show YOU artifacts on (★ in the list) agents devices config mac-mini agents.max-concurrent 4 # per-device settings; bare `devices config <name>` opens a menu (TTY) agents devices config --fleet agents.max-concurrent 2 # fleet-wide default every device inherits agents devices config mac-mini notes "runs the releases — don't reboot" # operator notes, repeat to append agents ssh mac-mini # hardened SSH: fails fast if offline, # PowerShell on Windows, password-from-Keychain, # auto-syncs your terminfo (Ghostty/kitty/…) so # backspace, colors & clear work on the remote scp mac-mini:/abs/log.json /tmp/ # fleet file transfer; host:path or abs local scp -r /tmp/src/ yosemite-s0:~/dst/ # ~ and $HOME expand on the REMOTE, never locally # Devices as a task backend agents cloud run "nightly benchmark" --device gpu-box --agent claude # task in cloud list AND devices ps ``` `agents devices list` shows normalized load, memory pressure, and an idle/light/busy/loaded headroom badge, plus a fleet-capacity summary (`164 cores · 421G free / 518G RAM`). It answers "which machine has room right now?" — the utilization signal the teammate scheduler doesn't yet see. It's **cache-first**: reads serve instantly from a stats cache the daemon warms (~every 3 min), probing only this machine locally plus any device missing from the cache; pass `--refresh` (or the shorter `--live`) to force a full live probe of every box. Cache-served output notes its age (`updated 2m ago — pass --refresh (--live) for a live probe`). `agents fleet status` answers "is my fleet OK?" at a glance: a one-line rollup (`● N online · ○ M offline`), a short **NEEDS ATTENTION** list where every item names the command that fixes it (offline → `check the box`, config drift or a stark CLI gap → `agents fleet apply --device <box>`, version skew → `agents upgrade --fleet`), then quiet per-device rows grouped by OS (macOS / Linux / Windows) showing just `name · capacity · load/mem · version`, with this machine flagged `▸ … ← this machine`. A healthy fleet reads in a few lines; orphaned versions are demoted to a one-line `agents prune` nudge in the footer. Pass `--verbose` for the full per-device grid — the **Auth column** (which agent accounts are actually logged in, per device, read from the auth-health cache — no network), plus the CLI-readiness and sync-drift columns. The Auth column has four buckets so it never cries wolf: `●live` (verified), `·present` (signed in but the agent has no live-probe endpoint — e.g. codex/grok — benign), `◐degraded` (soft/self-healing: expired-but-refreshing, rate-limited), and `○revoked` (server rejected — re-login now). Only `○` means a real re-login is needed. Run `agents fleet ping` to force a live re-verification across the fleet. `agents devices harnesses` answers "what can each box actually run right now?" — one row per installed `agent@version` across the fleet with its **account**, **signed-in**, **quota** (highest usage-window utilization; `*` = from the cached snapshot), and a single **ready** verdict (signed in AND not rate-limited). It SSH-probes each online device (bounded, so one unreachable box can't stall the glance) and reuses the daemon-warmed usage cache, so it never blocks on a per-account network fetch — pass `--refresh` (`--live`) for a live quota read. `agents devices accounts` is the same data through the **identity lens**: one row per account, collapsing the installs that share it (e.g. five claude versions on one email) and naming which harnesses use it — the fast way to see which accounts are logged in and healthy across every machine. Scope either with `--agents <csv>` / `--device <csv>`, and add `--json` for the machine-readable per-host rows. **Devices** (`agents devices`) are your machines: Tailscale nodes ingested by `agents devices sync` plus any added by hand, in one registry that every `--device` flag resolves against. On `--device` runs every `agents run` option is either forwarded (`--effort --env --timeout --loop …`), rejected loud (`--secrets` never crosses SSH implicitly), or consumed locally — nothing silently drops. See [docs/concepts.md](cli/docs/concepts.md#devices-placement-and-projects). Every `--device` command rides the shared SSH transport so host resolution, identity checks, environment forwarding, reconnect behavior, and multiplexing cannot drift between callers. See [fleet architecture](cli/docs/fleet.md). --- ## Teams <p align="center"> <img src="assets/teams.svg" alt="agents teams: parallel agents in dependency order, each detached in its own worktree with boundary contracts." width="100%" /> </p> ```bash agents teams create auth-feature # Research first, then implement, then test. agents teams add auth-feature claude "Research auth libraries" --name researcher agents teams add auth-feature codex "Draft the migration" --name migrator --after researcher agents teams add auth-feature claude "Write tests for the new code" --name tester --after migrator agents teams start auth-feature # Fires teammates whose deps are done agents teams status auth-feature # Who's working, what they changed, what they said ``` Teammates run detached -- close your terminal, they keep working. Check in with `teams status`, glance at a teammate's summary with `teams logs <name>` (add `--full` for the raw output), clean up with `teams disband`. Team state is observable via `agents teams list --json` / `agents teams status --json` (compact by default; add `--verbose` for the full per-teammate shape). 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/observability.md](cli/docs/observability.md). Placement, spawn, dependency, and non-zero-exit failures are persisted as sanitized evidence on the teammate record and shown by `teams status`. A failed root does not stop independent DAG branches; descendants name the failed or missing `--after` dependency that blocked them instead of remaining pending indefinitely. Capacity- or load-blocked placement stays pending with retryable evidence and is reconsidered on the next wave. `teams start` reports teammates that failed during the wave (`Failed this wave` / JSON `failed[]`) and exits non-zero when a wave produced only failures. A failed teammate keeps its record as evidence, so re-adding the same name needs `teams remove <team> <name>` first. --- ## Cloud Some work shouldn't tie up your laptop. `agents cloud run` hands a task to a managed provider that clones the repo, plans, implements, tests, and opens a PR -- while your terminal stays free. The `host` provider dispatches the same way onto machines you own: `agents cloud run "…" --device gpu-box` (tasks track in `agents cloud ps` and `agents devices ps` alike). <p align="center"> <img src="assets/cloud.svg" alt="agents cloud run dispatches one prompt to a managed provider (Rush, Codex, Cursor, Factory, or Antigravity) that runs while you keep working" width="100%" /> </p> ```bash # Dispatch and detach — streams to the cloud, not your terminal. agents cloud run "fix the flaky test in the payments suite" \ --provider rush --repo acme/api --branch main agents cloud list # what's running, queued, or needs review agents cloud logs <id> # re-attach and stream agents cloud message <id> "also update the changelog" # steer it mid-run agents cloud cancel <id> ``` Five managed backends behind one interface (`agents cloud providers`): | Provider | What runs | Notes | |---|---|---| | `rush` | Claude against a GitHub repo + branch | Opens a PR. Multi-repo via repeatable `--repo`; attach screenshots with `--image` for vision dispatch. | | `codex` | A pre-built Codex Cloud environment | Target it with `--env`. | | `factory` | `droid exec` on a cloud VM | Computer-use; pick the box with `--computer`. | | `antigravity` | Gemini managed agents | Antigravity harness in a remote sandbox. | | `cursor` | Cursor Cloud Agents | v1 REST API with repo, status, SSE, cancel, and follow-up runs. | Auto-routes each `--agent` to its native cloud, or pin the backend with `--provider`. `--json` on every subcommand for scripting. The same dispatch is a placement on `agents run`: `agents run claude "fix the flaky e2e" --cloud --repo acme/api` routes through the identical provider registry and tracks in `agents cloud list/status/logs` alike. `--cloud` sits alongside `--device`/`--lease` as one of three placements (local, machine, cloud) and is mutually exclusive with them; `--where cloud[:provider]` is the one-door spelling. Agents without a native cloud fail loud unless `--provider` is given. --- ## Workflows <p align="center"> <img src="assets/workflows.svg" alt="agents workflows: bundle an orchestrator prompt with optional subagents, skills, and plugins into a named, reusable pipeline invoked as one agent." width="100%" /> </p> Bundle an orchestrator prompt with optional subagents, skills, and plugins into a named, reusable pipeline. One bundle, one invocation. ```bash # Use a workflow — workflow name goes in the agent slot agents run code-review "review PR #42 on acme/api" # List + inspect agents workflows list agents workflows view code-review # Install from GitHub or local agents workflows add gh:yourteam/code-review agents workflows add ./my-workflow ``` A workflow is a directory: ``` ~/.agents/workflows/code-review/ WORKFLOW.md # YAML frontmatter + orchestrator system prompt subagents/ # optional: *.md files exposed to the orchestrator security.md style.md skills/ # optional: knowledge packs scoped to this workflow plugins/ # optional: plugin bundles ``` `WORKFLOW.md`'s Markdown body is the orchestrator's system prompt. Files under `subagents/` get copied to `~/.claude/agents/` at run time so the built-in Agent tool can dispatch to them by name — including in parallel. `skills/` and `plugins/` sync into the version home just for the run. ```yaml # WORKFLOW.md frontmatter --- name: Code Review description: Evidence-grounded PR review with file:line citations. model: opus tools: - Read - Grep - Bash - WebFetch --- ``` Workflows that need to write — post PR comments, edit files, send Slack — should run with `--mode edit`, or `--mode auto` on Claude Code, GitHub Copilot, and Codex. Reserve `--mode skip` (legacy alias: `full`) for last-resort bypasses. `agents run` defaults to `--mode plan` for other harnesses; Codex defaults to its safe writable profile. An explicit Codex `--mode plan` is read-only with network access. Resolution is project > user > system: a `<repo>/.agents/workflows/<name>/` overrides a same-named workflow in `~/.agents/workflows/`. Commit project workflows with your repo so teammates get the same pipeline. --- ## Plugins <p align="center"> <img src="assets/plugins.svg" alt="agents plugins: bundle skills, commands, hooks, and MCP servers under one manifest, mirrored into every installed agent version automatically." width="100%" /> </p> Bundle skills, commands, hooks, MCP servers, settings, and permissions under a single manifest. One source dir at `~/.agents/plugins/<name>/`, mirrored into every installed Claude / OpenClaw version automatically. ```bash # Add (install) from a git URL or local path — `install` is an alias for `add` agents plugins add hivemind@https://github.com/activeloopai/hivemind.git agents plugins add ./my-plugin # Apply to one agent (default version) or all supported agents sync --plugin rush-toolkit claude agents sync --plugin rush-toolkit ``` A plugin is a directory with a manifest: ``` ~/.agents/plugins/my-plugin/ .claude-plugin/plugin.json # required: { name, version, description } skills/<name>/SKILL.md # optional commands/*.md # optional hooks/hooks.json # optional — executable surface .mcp.json # optional — executable surface bin/, scripts/, settings.json # optional — executable surface permissions/ # optional — executable surface ``` On sync, agi-cli copies the plugin into each version home's marketplace (`<home>/.claude/plugins/marketplaces/agents-cli/plugins/<name>/`), registers the synthetic marketplace, and flips `settings.json#enabledPlugins[<name>@agents-cli] = true` so Claude / OpenClaw load it. ### Executable-surface gate Plugins that ship `hooks/`, `.mcp.json`, `bin/`, `scripts/`, `settings.json` (non-permissions), or `permissions/` can execute code on session events. agi-cli requires explicit consent before flipping `enabledPlugins`: ```bash # Hooks-bearing plugins copy in but stay disabled by default agents plugins add hivemind@https://github.com/activeloopai/hivemind.git \ --allow-exec-surfaces # Same gate on re-sync (e.g., after upstream updates) agents sync --plugin hivemind claude --allow-exec-surfaces ``` Skills, commands, and subagents are declarative and never trip the gate. The gate is per-plugin, per-install: consenting to hivemind doesn't grant blanket exec-surface trust to anything else. ### Version portability Plugins live in the user repo (`~/.agents/plugins/`), not inside any single version home. Switching Claude via `agents use claude@<v>` re-syncs the plugin into the new version automatically — no re-install. New Claude versions added later pick it up on their first sync. Project-level `<repo>/.agents/plugins/<name>/` overrides a same-named user plugin (resolution is project > user > system, same as every other resource). ### Install the agents-cli skill in any agent This repo is itself a Claude plugin marketplace and a [skills.sh](https://skills.sh) source. The `agents-cli` skill teaches any coding agent (Claude Code, Codex, Cursor, …) how to drive the `agents` CLI — so when you ask *"how do I run multiple coding agents in parallel?"* the agent surfaces `agents teams` instead of guessing. ```bash # Claude Code — add this repo as a marketplace, then install the plugin claude plugin marketplace add phnx-labs/agi-cli claude plugin install agents-cli@agents-cli # skills.sh — install the skill directly from the repo npx skills add phnx-labs/agi-cli ``` The manifest is `.claude-plugin/marketplace.json` (validate with `claude plugin validate .`); the skill source is [`skills/agents-cli/SKILL.md`](skills/agents-cli/SKILL.md). Its `description` carries the exact intents the runtime matches against — *run multiple coding agents in parallel*, *manage multiple Claude Code accounts*, *I hit my usage limit*, *resume a session on another machine*, *pin the agent CLI version* — each with a verified command recipe. --- ## Make it yours White-label the CLI. `agents setup mine` mints a **personally-named binary** — `jack` instead of `agents` — that _is_ agi-cli: same tool, your name, running the exact feature set you choose. Anyone can mint their own; Jack and Pranjal each get an independent brand. ```bash agents setup mine # wizard: pick a name, check off what to disable agents setup mine init jack --disable teams cloud # or non-interactively jack run claude "hello" # every agents verb, under your name jack --help # help, version, and errors all read "jack" ``` Manage brands with `agents setup mine list | toggle | remove`: ```bash agents setup mine toggle jack --disable-plugin rush --disable-skill deploy agents setup mine toggle jack --enable teams agents setup mine remove jack --purge ``` Under the hood, `init` creates a pass-through shim that selects a brand configuration; it does not fork the execution engine. Curated resources still resolve through the ordinary [resource architecture](cli/docs/resources.md). > Branded builds are free for personal and commercial use alike. New versions ship under FSL-1.1-Apache-2.0: every user and company may use, modify, and redistribute; only offering agents-cli itself as a competing commercial product or service is barred, and each version automatically becomes Apache-2.0 two years after release. --- ## Browser <p align="center"> <img src="assets/browser.svg" alt="browser drives your real, already-installed Chrome over CDP — the CLI issues start / refs / click / type / screenshot; the browser exposes numbered element refs and returns a token-efficient screenshot. Same fingerprint, same IP, so sites can't detect automation — it works where Playwright gets blocked." width="100%" /> </p> Give agents access to a real browser — no relay extension, no cloud service, no Playwright getting blocked. Browser driving is the standalone **`browser` CLI** (`@phnx-labs/browser-cli`; `agents setup browser` or `agents clis install browser` installs it). Each device declares its own browsers in its own `devices/<machine>/agents.yaml`. The fleet registry is the union of those files: a name declared by one device is identity-bearing (the daemon tunnels to that device); a name declared by several is fungible (use the local one). `--device` is only valid on `browser start`; later verbs resolve the device from the task. ```bash # Omit --profile to use this machine's default (`browser use <name>` sets it; # `browser profiles seed` creates a <browser>-local profile per installed browser). export AGENTS_BROWSER_TASK=$(browser start --url https://app.example.com) # Or pin a named profile to a specific browser (chrome, comet, brave, chromium, # edge, or custom) when you want isolation from auto-detect. browser profiles create work --browser chrome # `start` writes the resolved name (e.g. `swift-crab-falcon-a3f92b1c`) to stdout # and human-friendly commentary to stderr, so $(...) capture stays clean. export AGENTS_BROWSER_TASK=$(browser start --profile work --url https://app.example.com) browser refs # Get interactive element refs browser click 42 # Click element ref 42 browser type 15 --text "hello" # Type into element ref 15 browser screenshot # Smart resizing, token-efficient browser record start --fps 10 --duration 40 # Drive the page, then finalize a playable WebM under the task's recordings/ dir. browser record stop browser tabs # List tabs open for the current task browser tab focus tab123 # Switch focus to another tab browser done # Close task's tabs when finished # Need to address a different task in the same shell? Override per call: browser screenshot --task other-flow # Repeated observe/action loops: one Node process and daemon socket stay warm. printf '%s\n' \ '{"action":"screenshot","path":"/tmp/page.jpg"}' \ '{"action":"click","atX":320,"atY":540}' \ | browser stream --task "$AGENTS_BROWSER_TASK" ``` Recording resolves ffmpeg automatically. It reuses a usable binary on `PATH` or under `~/.agents/.cache`, and when none exists it installs through Homebrew on macOS, apt on Debian/Ubuntu, or the available platform package manager. If the automatic path cannot run, the error names the exact manual install command. ### Why this works where Playwright fails Playwright and Puppeteer spin up fresh browser instances with automation flags. Sites like LinkedIn, Google, and most finance apps detect and block them immediately. `browser` launches your existing residential Chrome (or Brave, Edge, Chromium) on your machine via CDP. Same browser fingerprint, same IP, same everything. Sites can't detect automation because you're using the same browser you'd use manually. ### Token-efficient automation The CLI handles the mechanical work so agents don't burn tokens on low-level browser commands. Screenshots are automatically resized without excessive compression — agents process smaller images while keeping the detail they need to make decisions. ### Profile isolation Multiple agents can run browser tasks simultaneously without stepping on each other. Each profile gets its own user data directory, cookies, and state. One agent logs into your work Slack, another into your personal email — no conflicts, no shared state. ```bash browser profiles create work-slack --browser chrome browser profiles create personal-gmail --browser chrome # Two agents, two profiles, no interference ``` ### Safe credential access Attach a [secrets bundle](#secrets) to a profile. The agent can log in without credentials in plaintext, and every secret access is recorded in the session log. ```bash browser profiles create bank --browser chrome --secrets bank-creds ``` ### Electron apps Control Electron apps (Slack, Discord, VS Code, your own app) with custom binaries: ```bash browser profiles create slack \ --browser custom \ --binary "/Applications/Slack.app/Contents/MacOS/Slack" \ --electron ``` ### Remote browsers Identity-bearing names tunnel automatically: declare `comet-local` only on the machine that holds the logins, and every other box reaches it through the daemon. `--device` on `start` binds a task to a specific box (fungible names, or an explicit pick). Later verbs reject `--device`. ```bash # Local CDP (discovers WebSocket URL automatically) browser profiles create local-debug \ --browser chrome \ --endpoint "http://localhost:9222" # Bind a task to a fleet device at start; later verbs resolve it from the task browser start --task post --device zion --url https://x.com/ browser screenshot --task post # Explicit SSH endpoint, declared on the machine that owns the browser browser profiles create staging \ --browser chrome \ --endpoint "ssh://deploy@staging.example.com?port=9222" # Cloud browser services (BrowserBase, Steel, etc.) browser profiles create cloud \ --browser chrome \ --endpoint "wss://connect.browserbase.com?apiKey=..." ``` --- ## Sign in Signing in is **optional**. Every local feature — `agents run`, sessions, teams, fleet dispatch, secrets, browser, computer — works with no account. Signing in unlocks the hosted surfaces: **team spaces** (`agents auth space`) and **owner notifications** (`agents send --to owner`). `agents auth` signs this machine in to **Phoenix ID**, the Phoenix Labs account layer behind these hosted surfaces. Sign-in is Google-only and runs a device-code flow: the CLI shows a code, your browser confirms it, and the CLI picks the session up. ```bash agents auth login # shows a code, opens a Phoenix-branded page agents auth whoami # who this machine is signed in as (--json) agents auth logout # clears THIS machine; no other device is touched agents auth space create "Design Team" # spaces are the team primitive agents auth space list # spaces you belong to agents auth space invite ada@example.com --role member agents auth space members # who is in it agents auth space role ada@example.com admin agents auth space remove ada@example.com # or remove yourself to leave ``` The session lives in this machine's agents state dir, so `logout` here signs out nothing else. `whoami` and every `space` subcommand take `--json`. `PHOENIX_ID_BASE` points the CLI at a different account service (a local one, for instance); it defaults to the deployed Phoenix ID service. Distinct from **Accounts** below: this is *your human identity*; those are the *harness credentials* an agent runs under. --- ## Accounts Choose an agent and an account, independently of its release number. Install the harness once; each account is a credential slot of that one install -- login, settings, and sessions stay in place when the executable is updated. Add an account on a headed (personal/desktop) device; workers pick up the durable credential automatically. ```bash agents add claude agents accounts add claude work # headed: native login + worker credential + sync agents accounts add codex personal agents accounts login claude#work # re-auth into the same slot agents accounts default claude work agents run claude#work agents accounts list agents view claude # accounts and usage, one row per identity agents view claude --versions # legacy diagnostic: every retained installation and actual release ``` `accounts add <harness> [name]` reuses the managed install, creates a HOME-shaped slot (no binary), drives the native login there, registers the fleet-wide row, and mints the worker credential (claude: `setup-token`; codex/grok/cursor/opencode: `--api-key` or a prompt). On a worker it refuses before any slot, install, or browser. An already-registered name or identity points at `accounts login`. `accounts login <harness>#<name>` re-auths into the same slot, fails closed on a different identity, and re-mints. Native login stays device-local; an account known on another device is not necessarily logged in here. Agents checks for updates to safely managed harness installations automatically. Disable this globally or per harness with `agents config set updates.auto false` or `agents config set updates.codex.auto false`. Use `agents update codex --check` to inspect eligibility without installing, or `agents update codex` to update that harness's installations. Running sessions and deliberately pinned installations are protected. See [installation and update policy](cli/docs/version-management.md). For a portable **provider credential** (API key / setup-token / bearer), the first arg is the account name, not a harness id: ```bash agents accounts add work --provider anthropic --auth setup-token agents accounts add gateway --provider openrouter --auth api-key \ --from-secrets openrouter.ai:OPENROUTER_API_KEY # import from an existing secrets bundle agents accounts add deepinfra --provider deepinfra --auth api-key agents accounts default claude work # claude uses `work` when --account is omitted agents accounts sync work --device yosemite-s0 # copy the bundle to a worker agents run claude --account work agents harness add deepinfra --account deepinfra ``` Mixing `accounts add <harness>` with `--provider` fails loud as ambiguous. One provider account **is** one `secrets` bundle -- `accounts add` creates it with secrets policy `never`, so a background launch never raises Touch ID. Harness-native OAuth stays where the harness put it and is never copied. ```bash agents accounts list agents accounts rename claude#work cloud agents accounts logout claude#work agents accounts remove claude#cloud ``` `accounts list` shows native logins and provider credentials together. `rename` / `remove` / `view` take `<harness>#<name>` when the same name exists on several harnesses; an ambiguous bare name is refused. `logout` signs out a native OAuth login; API-key accounts use `remove`. `accounts sync <name> --device <device>` is the only way a provider credential crosses machines. Selection order for a run is explicit `--account` / `<harness>#<name>`, then `accounts default` for that harness, then the harness's native/balanced behavior. The `connect` / `name` / `label` / `mint` / `attach` / `detach` / `switch` / `set-default` verbs are deleted; use `add` / `login` / `default` / `run <harness>#<name>` instead. --- ## Secrets Secrets are the standalone **`secrets` CLI** (`@phnx-labs/secrets-cli`). agi-cli does not ship the engine; it resolves bundles through `secrets` when a run asks for them. ```bash # Install (pick one — no extra env vars) agents clis install secrets # or npm i -g @phnx-labs/secrets-cli@0.1.8 # or, after agents is installed: agents setup secrets ``` ```bash # API keys in Keychain, not in .env files. secrets create prod-stripe secrets add prod-stripe STRIPE_SECRET_KEY # Prompts, stores in Keychain agents run claude "charge a test card" --secrets prod-stripe ``` > **Platform:** macOS Keychain, Linux libsecret / file store. On Windows (non-WSL), use environment variables or a `.env` file instead. The macOS broker is **not** the agents daemon. It is `secrets _agent-run` (started by `secrets start` or on first unlock), socket under `$SECRETS_HOME/.cache/helpers/secrets-agent/`. Linux has no broker. `agents daemon` never hosts it. <p align="center"> <img src="assets/secrets.svg" alt="How agi-cli secrets work: bundle definitions live in the macOS Keychain alongside their values, agi-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. ### Cross-machine sync Secrets are provided by the standalone [`@phnx-labs/secrets-cli`](https://github.com/phnx-labs/secrets-cli) engine (`agents setup secrets` installs it if missing). Its `push`/`pull` verbs move a bundle between machines by encrypting it and round-tripping it through `api.prix.dev` — no copy-paste, no `.env` files emailed to yourself: ```bash # On laptop: secrets create npm-tokens secrets add npm-tokens NPM_TOKEN # value lives in the local keychain/file store secrets push npm-tokens # encrypt + upload # On another machine: secrets pull npm-tokens # decrypt + restore locally agents run claude "..." --secrets npm-tokens # injects NPM_TOKEN automatically ``` Nothing about a secret's value ever lives in plaintext on disk, on either end. ### Per-secret metadata and rotation Tag each secret with `--type`, `--expires`, and `--note` so the bundle is self-documenting. `--expires` is always future-dated (`YYYY-MM-DD`); past or same-day values are rejected. Use `secrets rotate <bundle> <key>` to refresh a credential — `add` only creates new keys, `rotate` replaces the value and preserves metadata unless overridden. ```bash secrets add prod STRIPE_API_KEY --type api-key --expires 2027-01-15 --note "Live key, owner: payments-team" secrets rotate prod STRIPE_API_KEY --note "rotated after suspected leak" secrets list # EXPIRING column flags secrets due in the next 30 days ``` --- ## Daemon The session index, the feed stream, and usage/auth sync all run inside one always-on daemon per device. `agents daemon` is its runtime surface: ```bash agents daemon # identity + duplicates + per-service health (same as status) agents daemon status --json # machine-readable, for scripts / AGI EXT agents daemon start # start it (bypasses daemon.enabled -- the deliberate override) agents daemon stop # stop it agents daemon restart # stop then start agents daemon disable # persist daemon.enabled: false -- nothing auto-starts it agents daemon enable # clear the kill switch agents daemon reload # SIGHUP -- reload service toggles and the log level, no restart agents daemon services # health of every hosted service (session-index, feed-stream, ...) agents daemon services list # every toggleable service and its current on/off state agents daemon services enable recordings agents daemon services disable device-probe # stop the device probe without stopping the daemon agents daemon logs -f --level warn --since 1h agents daemon logs --level error --since 1h # each restart, with what was running when it happened agents daemon logs level debug # trace every tick and slow section, live; `level info` turns it off agents daemon doctor # one-shot health check; non-zero exit on problems agents daemon index roots # transcript directories the indexer scans (JSON) agents daemon index optimize # compact the FTS search index; no rows lost agents daemon index backfill tools --fleet # one-shot historical parse (also: resources, titles) ``` `agents daemon index` is foreground maintenance of the index the daemon's session-index service keeps current; it never starts or restarts the daemon. Each hosted responsibility (recordings, device probe, self-heal, self-update, account-state refresh, state-dir checks) is an independent toggle in `~/.agents/daemon/services.yaml`. Self-update checks npm on its own schedule, installs + verifies a newer agents-cli with the same primitives `agents upgrade` uses, then exits so the OS supervisor relaunches the daemon onto the new code — the daemon used to run with auto-update forced off and only picked up new code on a manual `agents daemon restart`. `agents daemon services list` shows every service; `enable|disable <id>` flips one. Missing keys default to enabled except the opt-in `recordings` service. Most services take effect on the next daemon start; recordings is registered while disabled so `agents recordings watch` can enable it live. Only `agents daemon start|stop|restart` owns the whole process lifecycle. The recordings commands change their own service state without evicting sibling work. Browser IPC is not a daemon service: the standalone `browser` CLI runs its own (`browser stop --service`). The CLI has no job scheduler: schedule recurring agent work with OS cron, a systemd timer, or launchd calling `agents run`. `disable` is a device-local kill switch: with it set, `agents feed watch` and `agents recordings` stop auto-starting the daemon, mirroring `systemctl disable` -- `agents daemon start` still works as the explicit override. --- ## Share Publishing an agent's HTML output to a shareable link now lives in the standalone `artifacts` CLI (`@phnx-labs/artifacts-cli`), not in `agents`. The `agents artifacts` command group was removed (PHNX-3992), the same split as secrets (PHNX-3989) and computer (PHNX-4075). Sign in and publish with it directly: ```bash artifacts auth login # Phoenix ID device-code sign-in artifacts share plan.html # publish the HTML and print the link ``` `sessions share <id>` (the standalone sessions CLI) renders a session transcript to HTML locally, then shells out to `artifacts share` to publish it, so a conversation becomes a shareable link the same way any other artifact does. --- ## PTY Real pseudoterminals for REPLs, TUIs, and interactive programs moved to the standalone [`term` CLI](https://github.com/phnx-labs/term-cli) (`npm i -g @phnx-labs/term-cli`), published separately (PHNX-4091). Same verbs, flags, and JSON shapes `agents pty` used to have: ```bash SID=$(term start) term exec $SID "python3" term screen $SID # Clean text, no ANSI -- what a human sees term write $SID "print('hello')\n" term stop $SID ``` `term`'s own sidecar server holds sessions alive between CLI calls and renders `screen` via a headless terminal emulator; sessions auto-clean after 30 minutes idle. See [term-cli's README](https://github.com/phnx-labs/term-cli#readme) for the full command reference. --- ## Portable setup ```bash # New machine? One command. agents setup # Installs CLIs, registers MCP servers, syncs skills/commands/rules/hooks, # sets up shims, configures defaults. Done. agents repo push # Snapshot your config to git ``` ### How config is layered Two repos with the same shape, different roles: | Repo | Role | Owner | |---|---|---| | `~/.agents/.system/` | **System repo** — core/built-in skills, commands, hooks, rules, MCP configs, permissions, and profiles that ship with `agi-cli`. The defaults every install gets. | Maintained upstream at [phnx-labs/.agents](https://github.com/phnx-labs/.agents) (formerly `.agents-system`) | | `~/.agents/` | **User repo** — your personal additions and overrides. This is what `agents repo push`/`pull` syncs. | You | **Version pinning:** `agents.yaml` at project root pins which agent version to use (like `.nvmrc` for Node). **Resource resolution:** When syncing resources (commands, skills, rules, hooks, MCP, permissions), the order is **project > user > system**. A `.agents/` directory at project root wins, then `~/.agents/`, then `~/.agents/.system/`. Same-named resources higher in the chain override lower ones; everything else unions in. Run `agents view --merged` to see the effective skills, commands, MCP servers, hooks, rules, plugins, workflows, and subagents, with each row tagged by its winning layer. See [docs/concepts.md](cli/docs/concepts.md) for the full mental model: DotAgents repos, resource kinds, and how resolution works end-to-end. Other useful commands: `agents doctor` checks CLI availability and resource sync drift, `agents view` shows per-account quota/rate-limit data for installed agents, `agents config budget` shows cross-vendor spend caps and current spend-to-cap (and enforces pre-flight estimates + a hard-cap kill-switch on every run — see [docs/observability.md](cli/docs/observability.md#budget-guardrails-agents-budget)), `agents import` adopts an existing unmanaged install, `agents prune trash` lists, restores (`agents prune trash restore <agent>@<version>`) and empties (`agents prune trash empty --older-than 30d`) soft-deleted version directories, and `agents subagents` installs reusable subagent definitions for parent-agent workflows. --- ## Menu bar On macOS, `agi-cli` puts a status item in your menu bar -- a live glance at what your agents are doing, plus a Spotlight-style bar for filing work without breaking focus. ```bash agents doctor # AGI Menu duplicates, stale or replaced helper, signing agents config set menubar.enabled false # turn it off on this Mac (true turns it back on) ``` The CLI installs and heals AGI Menu on its own: any `agents` command on a Mac installs the login item when it is missing and `menubar.enabled` is true. There is only ever **one** agents mark: the helper takes a lock at launch, so a second copy surfaces the running one's menu and exits instead of adding a duplicate icon. `agents doctor` names any duplicate or stale helper with the exact fix. AGI Menu updates itself about twice a day; `agents config set menubar.autoUpdate false` turns that off. See [AGI Menu updates](cli/docs/menubar.md#app-updates). The helper itself is AGI Menu, developed in [phnx-labs/agi-menu](https://github.com/phnx-labs/agi-menu) and published as a signed, notarized build on this repo's `menubar/v<x.y.z>` releases; the CLI downloads and verifies it on demand, so nothing is built on your machine. The dropdown surfaces a **NEEDS YOU** queue (agents waiting on a question, a plan review, or a permission prompt), and the running roster -- the same live state as `agents ps`, one click away. ### Quick-issue bar (⌘⇧O) Press `Cmd-Shift-O` anywhere for a thin capture surface: the prepared text field appears immediately while repo, thumbnail, and ticket rows hydrate in the background. Type a one-line note, `Cmd-V` to paste, and attach one or more recent screenshots (double-click a thumbnail to preview it in full). Submit, and a headless agent picks the right project from your recent sessions, investigates, and files the Linear ticket itself -- you never leave what you were doing. The bar also lists the **open Linear tickets of the repo you picked**, urgent first. Switching the repo switches the Linear project; typing filters the list, so an existing ticket shows up before you file a duplicate; and clicking a row (or `⌘1`-`⌘5`) dispatches that ticket to the selected agents -- **Run** implements it, **Plan** posts a plan as a ticket comment. <p align="center"> <img src="assets/menubar-quickissue.svg" alt="The Cmd-Shift-O quick-issue bar: a one-line note with attached screenshot thumbnails that a headless agent turns into a filed Linear ticket" width="100%" /> </p> --- ## Private skills Keep work or personal skills in a separate repo — public ones in `~/.agents/`, private ones in an extra repo that merges in at sync time. ```bash # Add a private repo for work-only skills agents repo add gh:yourname/.agents-work # Add with a custom alias agents repo add git@github.com:acme/team-skills.git --as acme agents repo list # Primary + every registered extra agents repo pull # Pull updates for all enabled extras agents repo disable acme # Stop merging without deleting agents repo remove acme # Unregister and delete the clone ``` Extras clone into `~/.agents-<alias>/` and ship the same layout as the primary (`skills/`, `commands/`, `hooks/`, `rules/`). Their contents merge into agent version homes after the primary's — so `~/.agents/` always wins on name collisions. `agents skills list` shows which repo each skill came from. --- ## Security & Privacy **The CLI binary has no built-in telemetry or phone-home path.** Everyday commands run locally; explicit features such as cloud dispatch and secrets push/pull send only the data needed for the action you invoke. Here's exactly what `agi-cli` stores locally and why. ### Event log Every agent run, version install, browser launch, and secrets access is logged to `~/.agents/.cache/logs/events-YYYY-MM-DD.jsonl`. This gives you a complete record of what agents did on your machine. ```bash # What gets logged (example event): { "ts": "2026-05-09T10:23:45Z", "event": "agent.run.end", "agent": "claude", "version": "2.1.121", "prompt": "Fix the auth bug in...", # truncated to 200 chars "durationMs": 45230, "exitCode": 0, "hostname": "your-mac", "platform": "darwin" } ``` **What's logged:** Operation type, agent, version, timing, prompt length + SHA-256 hash (raw text never stored), exit codes, errors, and secret bundle/key names with caller context. Argv entries that look like tokens or secret paths are redacted. **What's NOT logged:** Raw prompts, outputs, file contents, or secret values. **Permissions:** Logs directory is `0700` (owner-only), files are `0600`. Only you can read them. **Retention:** 7 days by default, then auto-pruned. **Opt out:** Set `AGENTS_DISABLE_EVENT_LOG=1` in your shell to disable completely. ### Session search Conversations with Claude, Codex, legacy Gemini, and other agents scatter across their native storage. Session search indexes them locally so you can find any conversation: ```bash sessions "auth middleware" # Full-text search across all agents sessions --agent claude --since 7d sessions --include tools --query 'program:git' --json agents daemon index backfill tools --fleet ``` The index lives at `~/.agents/.history/sessions/sessions.db` (SQLite + FTS5). Tool-call evidence is stored redacted and bounded; the standalone `sessions --include tools` searches it, reading another box over SSH with `--host`. Historical tool parsing is explicit via `agents daemon index backfill tools`; searches never parse transcripts. See [Sessions](#sessions-across-agents) for full usage. ### Secrets Secrets are provided by the standalone `@phnx-labs/secrets-cli` engine, stored in the OS keychain or an encrypted file store — never in plaintext files. Bundle definitions live alongside their values. ```bash secrets create my-keys secrets add my-keys API_KEY # Prompts for value, stores in the keychain/file backend ``` Move a bundle to another machine with `secrets push`/`secrets pull` (encrypted round trip through `api.prix.dev`). See [Secrets](#secrets) for full usage. ### Summary | Data | Location | Who can read | Opt out | |------|----------|--------------|---------| | Event log | `~/.agents/.cache/logs/` | You only (0600) | `AGENTS_DISABLE_EVENT_LOG=1` | | Session index | `~/.agents/.history/sessions/` | You only | Delete the directory | | Secrets | OS keychain / encrypted file store | You + apps you authorize | Don't use `secrets` | | Config | `~/.agents/` | You only | N/A | --- ## Compatibility Which DotAgents resources each agent CLI can load. Source of truth: [src/lib/agent-spec/agents.ts](cli/src/lib/agent-spec/agents.ts) (`capabilities`); gates use `supports(agent, cap, version)` from [src/lib/capabilities.ts](cli/src/lib/capabilities.ts). Full matrix also in [docs/concepts.md](cli/docs/concepts.md). > **Gemini CLI is hard-deprecated.** Google retired it for free, Pro, and Ultra tiers on **June 18, 2026** (announced at Google I/O 2026); the `gemini` command no longer serves requests on those tiers. agi-cli keeps the legacy `gemini` id only so old sessions/config can still be read. `agents add gemini`, `agents import gemini`, and `agents sync gemini` fail and point to **Antigravity CLI** (`antigravity`), Google's official successor — see [the transition notice](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/). | Agent | Versions | Hooks | MCP | Permissions | Skills | Commands | Plugins | Subagents | Rules | Workflows | |-------|----------|-------|-----|-------------|--------|----------|---------|-----------|-------|-----------| | Claude Code | yes | yes | yes | yes | yes | yes | yes | yes | `CLAUDE.md` | yes | | Codex CLI | yes | >= 0.116.0 | yes | no | yes | < 0.117.0 · skills ($name, >= 0.117) | >= 0.128.0 | no | `AGENTS.md` | no | | Antigravity | yes | yes | yes | yes | yes | yes | yes | no | `AGENTS.md` | no | | Grok Build | yes | yes | yes | yes | yes | skills ($name) | yes | no | `AGENTS.md` | no | | OpenClaw | yes | yes | yes | no | yes | gateway | yes | yes | `workspace/AGENTS.md` | no | | Cursor | yes | yes | yes | yes | yes | IDE + skills ($name) | yes | >= 2026.1.22 | `.cursorrules` | no | | OpenCode | yes | no | yes | >= 1.1.1 | yes | yes | no | no | `AGENTS.md` | no | | Copilot | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no | | Amp | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no | | Goose | yes | no | yes | no | no | no | no | no | `AGENTS.md` | no | | Droid | yes | yes | yes | >= 0.57.5 | >= 0.26.0 | yes | yes | yes | `AGENTS.md` | no | **Legend:** `yes` / `no` = synced or skipped at install time. `skills ($name)` = no file-based slash-command dir; behavior ships as a generated skill invoked with `$command`. `IDE + skills ($name)` = an IDE command file plus a generated skill for the CLI. `gateway` = OpenClaw resolves slash commands at runtime, not from synced files. Version suffixes are enforced at sync time — out-of-range versions are skipped with a clear message. **Host CLIs** (`agents clis`) are separate: YAML manifests under `~/.agents/clis/` install binaries onto your PATH (`gh`, `higgsfield`, etc.). They are not copied into per-agent version homes. ### agi-cli features (not agent-native resources) | Agent | Teams | Session index | |-------|-------|---------------| | Claude Code | yes | yes | | Codex CLI | yes | yes | | Cursor | yes | -- | | OpenCode | yes | -- | | Grok Build | yes | yes | | Antigravity | yes | -- | | Copilot | -- | yes | | OpenClaw, Amp, Goose | -- | -- | ### Version-gated sync | Capability | Agent | Gate | |------------|-------|------| | Hooks | Codex | >= 0.116.0 | | Skills | Droid | >= 0.26.0 | | Permissions | Droid | >= 0.57.5 | | File-based commands | Codex | < 0.117.0 (0.117+ uses command-as-skill) | | Plugins | Codex | >= 0.128.0 | Codex `0.117.0+` no longer reads `.codex/prompts/`; agi-cli converts slash commands into skills so they stay invocable as `$name`. OpenCode's plugin-based hook system is on the roadmap; hooks stay `no` until a writer ships. Slash commands can declare per-agent/version targeting in frontmatter (`agents:`, `since:`, `until:`). Gating applies when syncing from `~/.agents/commands/` (user/system) into version homes — project `.agents/commands/` files are read in place and are not filtered by `agents:`. ## FAQ ### Why use `agents` instead of `claude` / `codex` / `antigravity` directly? Claude Code, Codex CLI, Antigravity, Grok Build, and others 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 — every feature, with no account and no signup. `agents run`, sessions, teams, fleet dispatch, secrets, browser, and computer automation all work the moment you install. The optional `agents auth login` unlocks the hosted surfaces — team spaces (`agents auth space`) and owner notifications (`agents send --to owner`); there are no paid tiers. 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. `agi-cli` reads `agents.yaml` from the project root, walks up the directory tree, and routes to the correct binary per project. But it also manages agent-native resources (skills, MCP servers, commands, hooks, permissions) that language version managers don't touch. ### How does version switching actually work? Same approach as nvm, pyenv, and rbenv — battle-tested by millions of developers. When you install a version, we set up a shim script that resolves the version from `agents.yaml` and runs the right binary. Each version has an isolated config directory. No manual setup required. ### How do I share my agent setup with my team? Add a `.agents/` directory at your project root with your skills, hooks, rules, and commands. Resources merge automatically: project > user (`~/.agents/`) > system (`~/.agents/.system/`). Commit it with your repo and teammates get the same agent environment. ### Do I need to write separate rules for each agent (CLAUDE.md, .cursorrules, 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, `AGENTS.md` for Antigravity, `.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 CLI telemetry or phone-home.** API keys come from your shell environment or each agent CLI's existing auth, and remote calls only happen when you invoke a feature that requires them, such as cloud dispatch. For full transparency: `agi-cli` keeps a local event log at `~/.agents/.cache/logs/` so you can see exactly what agents did on your machine. Logs are owner-readable only (0600) and auto-prune after 7 days. Set `AGENTS_DISABLE_EVENT_LOG=1` to disable. See [Security & Privacy](#security--privacy) for details. ### Which platforms? macOS and Linux. Windows via WSL works but isn't first-class yet. **Secrets:** the standalone `secrets` CLI is cross-platform — macOS Keychain, Linux libsecret, or the `file` backend everywhere, including Windows (non-WSL) via environment variables or a `.env` file as a fallback when neither native store applies. Interactive runs spawn directly by default. Enable `tmux.enabled` on a device to give each run an addressable pane for `agents send --channel session`, injection, and `agents focus`; tmux-backed runs require tmux 3.2 or newer. ### Do I need Node.js? The installer tries Bun first (faster), falls back to npm. Node 22.5+ required at runtime. ### Can I use it in CI? Yes -- `agents run` is non-interactive by default. `--yes` auto-accepts prompts, `--json` for structured output. Pass explicit names and IDs instead of relying on interactive pickers. The auto-update prompt is suppressed automatically when stdin or stdout isn't a TTY. For headless environments where TTY detection misfires (k8s pods that allocate a PTY for stdout, cloud sandbox factories), set `AGENTS_CLI_DISABLE_AUTO_UPDATE=1` to skip the update check entirely -- no prompt, no network call. agi-cli also prints a one-time "star us on GitHub" line after your first successful `agents run`/`agents teams`. It's already skipped in CI, non-TTY, `--json`, and `--quiet` runs; set `AGENTS_NO_NUDGE=1` to suppress it everywhere. To update on demand instead of waiting for the prompt, run `agents upgrade` (add `-y` to skip the confirmation, or pass a version/dist-tag to install something other than latest). ### What happens to my config when I switch versions? Each version has its own isolated config directory. Switching just repoints a symlink — your per-version config stays untouched. On first migration (if you had a real `~/.claude/` directory before using agi-cli), that gets backed up once to `~/.agents/.history/backups/`. ### Does session search use RAG or semantic search? No — it's a SQLite + FTS5 full-text index. Fast, flexible, and robust. Agents can query sessions programmatically. Most commands support `--json` output for scripting with jq. ### How do I use custom or local models? Profiles (experimental — available by default). 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/agent-spec/agents.ts](cli/src/lib/agent-spec/agents.ts) -- each is a config object declaring commands dir, rules file, and capabilities. PRs welcome. ### What's the relationship to Phoenix Labs / Rush? `agi-cli` is an open client maintained by Phoenix Labs. Rush is a separate product. No Rush account required, no upsell. ## This monorepo also contains `@phnx-labs/agents-cli` is the published package and this README is its front page — but the repo houses more. No JS workspaces: each package installs and builds independently (`bun install` inside it). | Path | What | |---|---| | [`cli`](cli) | **The CLI** (this README) — version management, config sync, the session index and live roster, teams, cloud, fleet; fronts the standalone `sessions`, `browser`, `secrets`, and `computer` CLIs. | | [phnx-labs/agi-ext](https://github.com/phnx-labs/agi-ext) | **AGI EXT** — the VS Code extension (agent terminals as tabs + the Fleet dashboard). Moved to its own repo (RUSH-3189); separate product, own publish identity. | | `@phnx-labs/computer-cli` | The engine behind `computer`, published separately (`npm i -g @phnx-labs/computer-cli`): the Swift macOS Accessibility daemon, the C#/.NET Windows UI Automation daemon, and an install-free **VNC/RFB** backend for a Linux GUI desktop (`computer --vnc <host:port> screenshot` — coordinate-based screenshot/click/type/key/scroll against any x11vnc/Xvnc server). agents-cli supplies the app allow list, `--device` fleet resolution, and the action history. | | [`packages/session-tracker`](packages/session-tracker) | The `SessionStart` hook that writes live-session state **AGI EXT** reads back (agi-ext `src/core/liveSession.ts`) — not the CLI, which reads transcripts. | ## Contributing ```bash git clone https://github.com/phnx-labs/agi-cli cd agi-cli/cli bun install && scripts/build.sh --here # build + run the suite on this machine ``` Commands live in [`cli/src/commands/`](cli/src/commands/), libraries in [`cli/src/lib/`](cli/src/lib/), and tests sit beside their sources. [AGENTS.md](AGENTS.md) is the canonical engineering guide; [`cli/docs/README.md`](cli/docs/README.md) is the architecture index. ## License FSL-1.1-Apache-2.0 -- see [LICENSE](./LICENSE). Free for every user and company to use, modify, and redistribute; the only barred use is offering agents-cli itself as a competing commercial product or service. Each version automatically becomes Apache-2.0 two years after its release.