@phnx-labs/agents-cli 1.18.6 → 1.19.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.18.6
+
+**Claude**
+
+- Add auto permission mode support for Claude runs.
+- Remove a dead automatic mode flag from the Claude command template.
+
+**Teams**
+
+- Fix the cycle-detection test to accept running or failed teammate status.
+
 ## 1.18.5
 
 **Browser**
@@ -246,7 +257,7 @@
 **~/.agents split into .history/ and .cache/ buckets**
 
 - Durable runtime state (sessions, versions, runs, teams/agents, trash, backups) moves to ~/.agents/.history/.
-- Regenerable runtime state (shims, packages, cloud, logs, swarmify, helpers, browser runtime, fetch cache, dot-files) moves to ~/.agents/.cache/.
+- Regenerable runtime state (shims, packages, cloud, logs, companion, helpers, browser runtime, fetch cache, dot-files) moves to ~/.agents/.cache/.
 - Single-line gitignore for backing up ~/.agents/ — no more per-subdir cherry-picking.
 
 **Browser: profiles fold into agents.yaml + many new automation commands**
@@ -334,7 +345,7 @@
 
 - Added `--json` flag to `agents sessions list` and `agents sessions` for programmatic use
 - Output is a JSON array of session metadata (id, shortId, agent, version, account, project, cwd, filePath, topic, messageCount, tokenCount, timestamp)
-- Enables the Swarmify VS Code extension's "Agents: Session Resume" and "Agents: Session Trace" pickers
+- Enables the Companion VS Code extension's "Agents: Session Resume" and "Agents: Session Trace" pickers
 
 **OpenClaw workspace-aware sessions**
 

package/README.md

@@ -29,7 +29,7 @@
   <a href="https://github.com/NousResearch/hermes-agent" title="Hermes Agent"><img src="assets/harnesses/hermes.png" height="32" alt="Hermes Agent" /></a>
 </p>
 
-https://github.com/user-attachments/assets/cf0b2248-6672-4458-8027-b88525572f3e
+https://agents-cli.sh/demo.mp4
 
 ```bash
 npm install -g @phnx-labs/agents-cli
@@ -133,10 +133,10 @@ agents run claude "refactor auth module" --mode edit --fallback codex,gemini
 
 ```bash
 # Picks the signed-in account you haven't used recently.
-agents run claude "summarize recent commits" --rotate
+agents run claude "summarize recent commits" --strategy balanced
 ```
 
-`--rotate` cycles across installed versions of the same agent -- useful when you have multiple accounts and want to spread usage instead of burning through one.
+`--strategy balanced` spreads work across available versions of the same agent -- useful when you have multiple accounts and want to avoid burning through one.
 
 ### Chain agents
 
@@ -156,7 +156,7 @@ agents run claude "review this diff" --acp --json
 
 `--acp` routes through the [Agent Client Protocol](https://agentclientprotocol.com/) so you get a unified event stream -- `agent_message_chunk`, `tool_call`, `plan_update`, `stop_reason` -- instead of writing a parser per CLI. File writes and shell commands flow through agents-cli, which means `--mode plan` becomes a real sandbox: the write RPC is denied, not just unused.
 
-Works today with claude, codex, gemini, cursor, opencode, openclaw. Other harnesses keep running on the direct-exec path.
+ACP adapters are documented for claude, codex, gemini, cursor, opencode, and openclaw. Other harnesses keep running on the direct-exec path.
 
 ---
 
@@ -181,7 +181,7 @@ agents sessions a1b2c3d4 --last 3 --include user
 
 Interactive picker when you're in a terminal. Structured output (`--json`, `--markdown`, filtered by role or turn count) when piped.
 
-Backed by a SQLite + FTS5 index at `~/.agents-system/sessions/sessions.db` with incremental scanning -- warm reads in ~100ms. External tools can consume `--json` output as a programmatic observability layer; see [docs/05-sessions.md](docs/05-sessions.md) for the schema and [docs/06-observability.md](docs/06-observability.md) for the consumption patterns.
+Backed by a SQLite + FTS5 index at `~/.agents/.history/sessions/sessions.db` with incremental scanning -- warm reads in ~100ms. External tools can consume `--json` output as a programmatic observability layer; see [docs/05-sessions.md](docs/05-sessions.md) for the schema and [docs/06-observability.md](docs/06-observability.md) for the consumption patterns.
 
 ---
 
@@ -214,7 +214,7 @@ Custom endpoints (Ollama, vLLM) work too -- drop a YAML in `~/.agents/profiles/`
 name: local-qwen
 host: { agent: claude }
 env:
-  ANTHROPIC_BASE_URL: https://ollama.internal
+  ANTHROPIC_BASE_URL: https://ollama.example.com
   ANTHROPIC_MODEL: qwen3.6:35b
 auth:
   envVar: ANTHROPIC_AUTH_TOKEN
@@ -402,11 +402,11 @@ Merge order: profile env < `--secrets` < `--env K=V`. A missing keychain item ab
 
 ### Cross-machine sync via iCloud Keychain
 
-Pass `--icloud-sync` when creating a bundle and both the bundle definition and its values are written to the iCloud-synced keychain. Sign into the same iCloud account on another Mac (with iCloud Keychain enabled) and the bundle appears there within seconds — no copy-paste, no `.env` files emailed to yourself, no shared secret stores.
+Secret bundles sync through iCloud Keychain by default. Sign into the same iCloud account on another Mac (with iCloud Keychain enabled) and the bundle appears there within seconds — no copy-paste, no `.env` files emailed to yourself, no shared secret stores. Pass `--no-icloud-sync` when creating a bundle if it should stay device-local.
 
 ```bash
 # On laptop:
-agents secrets create npm-tokens --icloud-sync
+agents secrets create npm-tokens
 agents secrets add npm-tokens NPM_TOKEN          # value lives in iCloud Keychain
 
 # On another Mac (same iCloud account):
@@ -414,7 +414,7 @@ agents secrets list                              # npm-tokens is already there;
 agents run claude "..." --secrets npm-tokens     # injects NPM_TOKEN automatically
 ```
 
-Under the hood, `--icloud-sync` routes writes through a notarized helper app (`AgentsKeychain.app`) that holds the entitlement macOS requires for `kSecAttrSynchronizable`. Bundles without `--icloud-sync` stay device-local.
+Under the hood, synced bundles route writes through a notarized helper app (`AgentsKeychain.app`) that holds the entitlement macOS requires for `kSecAttrSynchronizable`. Bundles created with `--no-icloud-sync` stay device-local.
 
 Bundle definitions sync via iCloud Keychain too — no `agents repo push` needed for secrets, no recreate step on each Mac. Nothing about secrets ever lives in plaintext on disk.
 
@@ -467,7 +467,7 @@ A sidecar server holds sessions alive between CLI calls. `screen` renders via xt
 
 ```bash
 # New machine? One command.
-agents init
+agents setup
 
 # Installs CLIs, registers MCP servers, syncs skills/commands/rules/hooks,
 # sets up shims, configures defaults. Done.
@@ -490,6 +490,8 @@ Two repos with the same shape, different roles:
 
 See [docs/00-concepts.md](docs/00-concepts.md) for the full mental model: DotAgents repos, resource kinds, and how resolution works end-to-end.
 
+Other useful commands: `agents doctor` checks CLI availability and resource sync drift, `agents usage` shows available quota/rate-limit data for installed agents, `agents import` adopts an existing unmanaged install, `agents trash` lists and restores soft-deleted version directories, and `agents subagents` installs reusable subagent definitions for parent-agent workflows.
+
 ---
 
 ## Private skills
@@ -515,11 +517,11 @@ Extras clone into `~/.agents-system/.repos/<alias>/` and ship the same layout as
 
 ## Security & Privacy
 
-**Everything stays on your machine.** No telemetry, no cloud sync (unless you opt into iCloud Keychain for secrets), no phone-home. Here's exactly what `agents-cli` stores locally and why.
+**The CLI binary has no built-in telemetry or phone-home path.** Routine commands run locally; explicit features such as cloud dispatch and iCloud Keychain sync send only the data needed for the action you invoke. Here's exactly what `agents-cli` stores locally and why.
 
 ### Event log
 
-Every agent run, version install, browser launch, and secrets access is logged to `~/.agents/logs/events-YYYY-MM-DD.jsonl`. This gives you a complete record of what agents did on your machine.
+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):
@@ -553,7 +555,7 @@ agents sessions "auth middleware"     # Full-text search across all agents
 agents sessions --agent claude --since 7d
 ```
 
-The index lives at `~/.agents/sessions/sessions.db` (SQLite + FTS5). Nothing leaves your machine. See [Sessions](#sessions-across-agents) for full usage.
+The index lives at `~/.agents/.history/sessions/sessions.db` (SQLite + FTS5). Nothing leaves your machine. See [Sessions](#sessions-across-agents) for full usage.
 
 ### Secrets
 
@@ -564,14 +566,14 @@ agents secrets create my-keys
 agents secrets add my-keys API_KEY    # Prompts for value, stores in Keychain
 ```
 
-With `--icloud-sync`, secrets sync via iCloud Keychain to your other Macs. Without it, they stay device-local. See [Secrets](#secrets) for full usage.
+By default, secrets sync via iCloud Keychain to your other Macs. With `--no-icloud-sync`, they stay device-local. See [Secrets](#secrets) for full usage.
 
 ### Summary
 
 | Data | Location | Who can read | Opt out |
 |------|----------|--------------|---------|
-| Event log | `~/.agents/logs/` | You only (0600) | `AGENTS_DISABLE_EVENT_LOG=1` |
-| Session index | `~/.agents/sessions/` | You only | Delete the directory |
+| Event log | `~/.agents/.cache/logs/` | You only (0600) | `AGENTS_DISABLE_EVENT_LOG=1` |
+| Session index | `~/.agents/.history/sessions/` | You only | Delete the directory |
 | Secrets | macOS Keychain | You + apps you authorize | Don't use `agents secrets` |
 | Config | `~/.agents/` | You only | N/A |
 
@@ -629,19 +631,19 @@ Your choice. We hand off to the original CLI process — use your existing subsc
 
 ### Does it store my API keys or send telemetry?
 
-**No telemetry, no phone-home.** Everything stays local. API keys come from your shell environment or each agent CLI's existing auth.
+**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: `agents-cli` keeps a local event log at `~/.agents/logs/` so you can see exactly what agents did on your machine. Logs are owner-readable only (0600) and auto-prune after 30 days. Set `AGENTS_DISABLE_EVENT_LOG=1` to disable. See [Security & Privacy](#security--privacy) for details.
+For full transparency: `agents-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 30 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.
 
-**macOS-only features:** Keychain-based secrets (`agents secrets`, `agents profiles login`) require macOS. The `--icloud-sync` flag on bundles requires macOS + iCloud Keychain enabled. On Linux, use environment variables or `.env` files for API keys. Native Linux credential store support is planned.
+**macOS-only features:** Keychain-based secrets (`agents secrets`, `agents profiles login`) require macOS. Default iCloud sync for bundles requires macOS + iCloud Keychain enabled; use `--no-icloud-sync` for device-local bundles. On Linux, use environment variables or `.env` files for API keys. Native Linux credential store support is planned.
 
 ### Do I need Node.js?
 
-The installer tries Bun first (faster), falls back to npm. Node 18+ required at runtime.
+The installer tries Bun first (faster), falls back to npm. Node 22.5+ required at runtime.
 
 ### Can I use it in CI?
 

package/dist/commands/browser.js

@@ -9,7 +9,7 @@ import { parseTargetFilter } from '../lib/browser/service.js';
 import { sendIPCRequest } from '../lib/browser/ipc.js';
 import { browserTaskPicker } from './browser-picker.js';
 import { isInteractiveTerminal } from './utils.js';
-import { registerCommandGroups } from '../lib/help.js';
+import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 /**
  * Resolve which browser task a command targets. Order:
  *   1. `--task <name>` flag (explicit per-command override)
@@ -50,7 +50,30 @@ const BROWSER_HELP_GROUPS = [
 export function registerBrowserCommand(program) {
     const browser = program
         .command('browser')
-        .description('Browser automation via CDP');
+        .description('Launch and drive browser profiles via the Chrome DevTools Protocol. Power-tool for the `browser` skill.');
+    setHelpSections(browser, {
+        examples: `
+      # List configured browser profiles
+      agents browser profiles list
+
+      # Create a Chrome profile pointed at a CDP endpoint
+      agents browser profiles create work --browser chrome --endpoint http://localhost:9222
+
+      # Start a session against a profile
+      agents browser start work
+
+      # Drive the page
+      agents browser navigate https://example.com
+      agents browser screenshot
+
+      # End the session when done
+      agents browser done
+    `,
+        notes: `
+      Most agent workflows should use the 'browser' skill instead of raw subcommands.
+      The skill wraps profile selection, snapshotting, and tunneling.
+    `,
+    });
     registerProfilesCommands(browser);
     registerTaskCommands(browser);
     registerCommandGroups(browser, BROWSER_HELP_GROUPS);

package/dist/commands/cloud.js

@@ -56,13 +56,13 @@ Providers:
 
 Examples:
   # Dispatch a quick fix to Rush Cloud and stream the output
-  agents cloud run "fix the flaky e2e in apps/web/tests/checkout.spec.ts" --provider rush --repo getrush/rush --branch main
+  agents cloud run "fix the flaky e2e in apps/web/tests/checkout.spec.ts" --provider rush --repo acme/example --branch main
 
   # Fire-and-forget (returns the task id, no streaming)
-  agents cloud run "bump tailwind to v4 and fix the breaks" --provider rush --repo getrush/rush --no-follow
+  agents cloud run "bump tailwind to v4 and fix the breaks" --provider rush --repo acme/example --no-follow
 
   # Multi-repo dispatch: touch both rush and rush-extension in one task
-  agents cloud run "rename POST /v1/charge -> /v2/charge across server + extension" --provider rush --repo getrush/rush --repo getrush/rush-extension
+  agents cloud run "rename POST /v1/charge -> /v2/charge across server + extension" --provider rush --repo acme/example --repo acme/example-extension
 
   # Codex Cloud against a saved environment
   agents cloud run "add pytest fixtures for the new billing module" --provider codex --env env_a1b2c3 --agent codex --timeout 30m

package/dist/commands/computer.d.ts

@@ -0,0 +1,6 @@
+import { Command } from 'commander';
+import { resolveHelperExec, resolveSocketPath } from '../lib/computer-rpc.js';
+export declare function registerComputerCommand(program: Command): void;
+export declare function registerComputerSubcommands(program: Command): void;
+export { resolveHelperExec as resolveHelperPath };
+export { resolveSocketPath };