@phnx-labs/agents-cli 1.19.2 → 1.20.3

package/CHANGELOG.md

@@ -1,5 +1,145 @@
 # Changelog
 
+## 1.20.3
+
+**`agents run` startup latency (stale-while-revalidate the usage probe + memoize agents.yaml)**
+
+- The default `agents run` strategy is `available`, which calls `getUsageInfoForIdentity` to skip rate-limited accounts. With a 2-minute cache, every cold invocation past that window made a blocking `fetch` to `api.anthropic.com/api/oauth/usage` (5 s timeout, plus an optional 15 s OAuth token refresh) before `spawn(claude)` — so `agents run claude` regularly stalled 5–8 s with nothing on screen after the rotation banner.
+- The cache is now stale-while-revalidate: fresh (<2 min) returns instantly with no network, stale-but-recent (<24 h) returns the cached snapshot instantly and refreshes in the background, and only a fully cold / >24 h cache blocks on the live fetch. The background refresh defers its first await past `setImmediate` so the synchronous Keychain CLI call (`security find-generic-password`, invoked by `loadClaudeOauth`) cannot block the foreground caller — that's how an SWR returns "instantly" even while the refresh is technically still on its first sync step.
+- `readMeta()` had a `metaCache` module global plus `writeMetaUnlocked` cache-invalidation logic wired in years ago — but no read path ever consulted the cache. So every call did 2x `fs.readFileSync` + 2x `yaml.parse` on system + user `agents.yaml`, and hot callers (`getConfiguredRunStrategy`, `getGlobalDefault`, `getVersionResources`, `ensureVersionResourcePatterns`) fire it multiple times per `agents run`. The read path now consults the cache, keyed on the combined mtime of both source files — out-of-band edits still invalidate on the next stat, and in-process writers already clear it.
+
+## 1.20.2
+
+**Grok and Antigravity Support & Documentation**
+
+- **Grok CLI Integration**: Added support for installing Grok via `agents add grok@<version>`, which invokes the official xAI installer with the specified version. Grok MCP server configuration paths (via `config.toml`) and memory file mapping are now correctly documented.
+- **Antigravity (AGY) CLI Integration**: Added support for the Google Antigravity CLI. Since the AGY installer doesn't support version-pinned installs currently, `agents add agy` uses the `latest` version. Documented the canonical config path `~/.gemini/antigravity-cli/` and its `mcp_config.json`.
+- **Documentation**: Updated `02-resource-sync.md` to reflect accurate MCP mappings and memory file symlinks for both Grok and Antigravity.
+- **Profiles**: Hardened presets with verified 2026 model IDs and added generic proxy configuration. Show custom profiles in agents view.
+
+## 1.20.1
+
+**Agents selector (auto-install missing versions + unified `@all` everywhere)**
+
+- `--agents claude@2.1.999` used to hard-error when 2.1.999 wasn't installed. Now the CLI prompts to install it inline and continues (auto-install with `--yes`). No more breaking flow to run `agents add` first.
+- `--agents claude@all` and the bare `all` literal now work across every callsite that takes `--agents` — previously `agents install gh:...`, `mcp register`, `mcp remove`, and inline `mcp add` had diverged from the canonical syntax and threw "Version all is not installed" despite the help text advertising it. Selector is unified end-to-end.
+
+**Prompt (fail loud on non-TTY + `@all` syntax in picker)**
+
+- Scripts that called `agents <resource> add` with no `--agents` and no `--yes` used to silently auto-pick a default version. That hid scripted misuse behind unpredictable picks. The non-TTY path now throws with a clear pointer at the new syntax: `--agents claude@all` (every installed version of Claude), `--agents all` (every capable agent at all versions), or `--agents claude@2.1.141` (one specific version).
+- `--agents` parsing in `<resource> add` understands `@all` and the bare `all` literal; `promptAgentVersionSelection`'s picker surfaces version counts when there's more than one installed, mirroring what `@all` would target.
+
+**Resources / install (`gh:` form sniffs every type, `mcp add gh:`, `--names` + `@all` unified across resource add)**
+
+- `agents install gh:<owner>/<repo>` now sniffs every resource type in the source repo (commands, skills, hooks, MCP, permissions, profiles, subagents, workflows) instead of requiring one `--types` per kind. Pass `--types skills,workflows` to narrow.
+- New `agents mcp add gh:<owner>/<repo>` form — install MCP servers directly from a git source, parallel to the other `<resource> add gh:` paths.
+- `<resource> add` accepts `--names` and `@all` uniformly across commands, skills, hooks, MCP, permissions, profiles, rules, subagents, workflows — same flags, same semantics, regardless of resource kind.
+
+**Profiles (interactive `create` wizard, gateway + self-hosted presets)**
+
+- New `agents profiles create` command — interactive wizard to assemble a profile from gateway or self-hosted presets (OpenRouter, OpenAI-compatible) without hand-writing YAML.
+- `--smoke-test` exercises the resolved env block against the configured endpoint before writing the profile.
+
+**Feedback (in-CLI bug / idea / question routing)**
+
+- New `agents feedback` command — collects a short description + optional category (bug, idea, question) and routes to the project's tracker without leaving the terminal.
+
+**Routines (real exit codes for detached scheduled runs)**
+
+- `monitorRunningJobs` used to hardcode `status: 'failed'` whenever it detected that a detached child had exited — `executeJobDetached` fires-and-forgets, so the real exit code was unreachable. Every scheduler-driven routine ended up labeled `failed/exitCode: null`, even when the agent completed cleanly.
+- Fix: when finalizing a vanished child, scan the tail of its stream-json `stdout.log` for Claude's `type: result` terminator (which carries `is_error`). If found, set `status` and `exitCode` from it. Only fall back to `failed` when no result marker exists (process was killed mid-run).
+- Routines list cell rendering hardened around 7-day retention boundaries.
+- Codex/Gemini run finalization continues to fall back to `failed` until their stream tail parsers are added.
+
+**Security**
+
+- `security(cli)`: eliminated `shell: true` from manifest-driven installs — closes a command-injection vector in `install`/`add` paths that took git URLs or shell-interpolated metadata.
+- `security(logs)`: prompts and tokens are redacted before `events.jsonl` is written, and event retention is shortened from 30d to 7d. Reduces blast radius on accidental disclosure.
+- `security(exec)`: strip loader env vars (`DYLD_*`, `LD_*`, `NODE_OPTIONS`) from environments propagated to child agents — avoids passing host-process loader state into spawned binaries.
+- `security(browser)`: CDP origin allowlist replaces the previous wildcard — only `localhost` and explicitly configured browser hosts can speak CDP into a session.
+- `security(ci)`: keychain helper SHA is verified at publish time, so a tampered helper binary cannot ride a release.
+
+**Copilot (fix user-scoped MCP path)**
+
+- Copilot's user-scoped MCP path now correctly resolves to `mcp-config.json` (the path the IDE actually reads) instead of the legacy filename. Fixes user-level MCP registrations not appearing in Copilot sessions.
+
+**Docs**
+
+- Full docs site IA shipped: browser, cloud, computer, hooks, plugins, profiles, pty, secrets, subagents, teams, workflows.
+- Brand identity block: `agents-cli` is Phoenix Labs OSS, not part of the Rush brand — guards downstream agents against pulling Rush styling into this project.
+
+**Build / install**
+
+- Staged dev install tarball strips `prepack` and `prepare` hooks so side-by-side dev installs don't accidentally re-run the full publish pipeline locally.
+- `test(jobs)`: un-break 3 stale assertions on main.
+
+## 1.20.0
+
+**Routines (overdue detection + catchup)**
+
+- Detect routines whose most recent scheduled fire was missed (laptop off, daemon crashed, reboot). The daemon logs them on startup and pops a native desktop notification (`osascript` on macOS, `notify-send` on Linux).
+- `agents routines list` annotates overdue rows with `(overdue)` and prints a footer pointing at the catchup command.
+- New `agents routines catchup` command: lists overdue routines and fires them in the background under the scheduler. `--dry-run` lists without triggering.
+- `JobScheduler.schedule` now sets croner's `catch: true` and forwards `timezone` defensively, so a synchronous throw in one job's callback can't kill the whole cron loop.
+
+**Landing page (agents-cli.sh)**
+
+- Expanded the homepage with seven new sections: rotate accounts (`--rotate`), parallel teams (`agents teams`), browser automation, cross-agent session search, routines/cron, keychain secrets, and machine-to-machine sync (`agents drive`).
+- Rewrote meta description + lede to spell out the actual feature set (pin versions, swap models, rotate accounts, drive a browser, spawn parallel teams, schedule on cron) instead of just "same interface, on your machine."
+
+**Codex (commands-as-skills sync fix)**
+
+- Fix recurring "N commands new" prompt on `agents view codex` for Codex >= 0.117.0. `getActuallySyncedResources` now detects converted command-skills via the `agents_command` marker in `~/.codex/skills/<name>/SKILL.md` instead of only scanning the empty legacy `prompts/` directory.
+- Summary and selection prompts are version-aware: the static `COMMANDS_CAPABLE_AGENTS` gate is replaced by `supports(agent, 'commands', version)` so the "X commands" line only appears for versions that can actually take them.
+- Generalize `shouldInstallCommandAsSkill` beyond Codex — any agent where commands are gated off and skills are on (e.g. Grok) now gets the same automatic slash-command → skill conversion at install/sync time.
+
+**Grok Build (first-class support)**
+
+- Add `grok` as a first-class supported agent (AgentId + full registry entry using official `~/.grok/README.md` paths).
+- Implement proper binary resolution from `~/.grok/downloads/`.
+- Add `GROK_HOME` isolation to generated shims for true versioned config (skills, hooks, plugins, agents/, MCP, memory, etc.).
+- Extend `installVersion` to support Grok via its official installer script (`curl ... -s <version>`).
+- Update shims, exec templates, MCP path helpers, session helpers, unmanaged detection, and docs.
+- `agents add grok@<ver>`, `agents use grok@<ver>`, resource sync, and shims now work end-to-end for Grok Build.
+
+**Browser**
+
+- `agents browser start --record` convenience flag for one-shot recording sessions.
+- Auto-discover per-site `SKILL.md` on `browser start` so skills appear under the active task without manual wiring.
+- Auto-pick a Chromium-family browser when `--profile` is omitted; the limitation is surfaced in `--help` and the auto-pick error.
+- No more stacktraces when the daemon is down or CDP is unreachable — error paths print a single human-readable line.
+- Drop the Playwright `bundled-chromium` devdependency.
+
+**Secrets / Keychain**
+
+- `agents secrets list` and `agents run --secrets <bundle>` collapse to one Touch ID prompt per bundle instead of one per key. Previously every secret in a bundle would re-prompt for keychain unlock.
+
+**Sessions**
+
+- Extract `groupActiveSessions` into a tested helper for `--active` window grouping.
+- Propagate `windowid` from live-terminals into the active session record.
+
+**Copilot**
+
+- Emit `COPILOT_HOME` in the shim and exec env builder for versioned isolation.
+- Wire the Copilot session dir and `.jsonl` extension into the sessions reader.
+
+**OpenClaw**
+
+- Carry OpenClaw user data forward on version switch.
+
+**Teams**
+
+- Warn loudly when `--after` teammates reference a name whose watch process never launched, instead of silently sitting in pending state.
+
+**Plugins**
+
+- Use `'directory'` source discriminator (not `'local'`) for marketplace registration so plugins reload correctly.
+
+**Dependencies**
+
+- Bump `@inquirer/prompts` 7.10.1 → 8.5.1, `diff` 8.0.4 → 9.0.0, `tsx` 4.22.2 → 4.22.3, `actions/setup-node` 4.4.0 → 6.4.0.
+
 ## 1.18.6
 
 **Claude**

package/README.md

@@ -11,7 +11,7 @@
   <a href="https://github.com/phnx-labs/agents-cli"><img src="https://img.shields.io/badge/github-phnx--labs%2Fagents--cli-blue?style=flat-square" alt="github" /></a>
 </p>
 
-**The missing toolchain for CLI coding agents.** Pin versions to escape regressions. Build hooks to control agent behavior, or skills to improve them. Then share your agent environment with your team, or clone it to any machine with one command.
+**The missing toolchain for CLI coding agents.** Run any agent on your existing subscription. Spawn parallel teams in isolated terminals. Schedule routines, drive browsers and Electron apps, and store secrets behind Touch ID — 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>
@@ -27,6 +27,8 @@
   <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)"><strong>Grok</strong></a>
 </p>
 
 https://agents-cli.sh/demo.mp4
@@ -79,7 +81,7 @@ agents:
   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` / `gemini` to the right version automatically. Each version gets its own isolated home -- switching backs up config and re-syncs resources.
+Think `requirements.txt` for CLI coding agents, on steroids. A shim reads `agents.yaml` from the project root and routes `claude` / `codex` / `gemini` / `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@2.0.65     # Install a specific version
@@ -154,9 +156,9 @@ Supports plan (read-only) and edit modes, effort levels, JSON output for scripti
 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.
+`--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 agents-cli, which means `--mode plan` becomes a real sandbox: the write RPC is denied, not just unused.
 
-ACP adapters are documented for claude, codex, gemini, cursor, opencode, and openclaw. Other harnesses keep running on the direct-exec path.
+ACP adapters are documented for claude, codex, gemini, cursor, opencode, openclaw, and grok. Other harnesses keep running on the direct-exec path.
 
 ---
 
@@ -281,7 +283,7 @@ A workflow is a directory:
 ---
 name: Code Review
 description: Evidence-grounded PR review with file:line citations.
-model: claude-opus-4-7
+model: opus
 tools:
   - Read
   - Grep
@@ -296,15 +298,70 @@ Resolution is project > user > system: a `<repo>/.agents/workflows/<name>/` over
 
 ---
 
+## Plugins
+
+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
+# Install from a git URL or local path
+agents plugins install hivemind@https://github.com/activeloopai/hivemind.git
+agents plugins install ./my-plugin
+
+# Apply to one agent (default version) or all supported
+agents plugins sync rush-toolkit claude
+agents plugins sync 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, agents-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. agents-cli requires explicit consent before flipping `enabledPlugins`:
+
+```bash
+# Hooks-bearing plugins copy in but stay disabled by default
+agents plugins install hivemind@https://github.com/activeloopai/hivemind.git \
+  --allow-exec-surfaces
+
+# Same gate on re-sync (e.g., after upstream updates)
+agents plugins sync 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).
+
+---
+
 ## Browser
 
 Give agents access to a real browser — no relay extension, no cloud service, no Playwright getting blocked.
 
 ```bash
-# Create an isolated profile for automation
+# First run: omit --profile and we auto-pick the first installed Chromium-family
+# browser. macOS prefers Chrome > Brave > Edge > Chromium > Comet; Linux prefers
+# Chrome > Chromium > Brave > Edge; Windows prefers Edge (always preinstalled) >
+# Chrome > Brave. The auto-picked profile is saved as "default" for later runs.
+export AGENTS_BROWSER_TASK=$(agents 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 "default".
 agents browser profiles create work --browser chrome
-
-# Start a task once, then bind it to this shell — every later command picks it up.
 # `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=$(agents browser start --profile work --url https://app.example.com)
@@ -384,6 +441,9 @@ agents browser profiles create cloud \
 
 ## Secrets
 
+> **Platform:** `agents secrets` requires macOS Keychain or Linux libsecret.
+> On Windows (non-WSL), use environment variables or a `.env` file instead.
+
 ```bash
 # API keys in Keychain, not in .env files.
 agents secrets create prod-stripe
@@ -538,11 +598,11 @@ Every agent run, version install, browser launch, and secrets access is logged t
 }
 ```
 
-**What's logged:** Operation type, agent, version, timing, truncated prompts (first 200 chars), exit codes, errors. **What's NOT logged:** Full prompts, outputs, file contents, secret values (only bundle names).
+**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:** 30 days by default, then auto-pruned.
+**Retention:** 7 days by default, then auto-pruned.
 
 **Opt out:** Set `AGENTS_DISABLE_EVENT_LOG=1` in your shell to disable completely.
 
@@ -603,7 +663,7 @@ Codex command sync is version-aware: Codex `0.116.x` and older receive slash com
 
 ### Why use `agents` instead of `claude` / `codex` / `gemini` directly?
 
-Claude Code, Codex CLI, and Gemini CLI each have their own config format, MCP setup, version management, and skill system. If you use more than one, you maintain N copies of everything. `agents` gives you one interface, one config source, and one place to pin versions -- plus features the individual CLIs don't ship: cross-agent pipelines, shared teams, unified session search, and project-pinned versions like `.nvmrc`.
+Claude Code, Codex CLI, Gemini CLI, 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?
 
@@ -633,7 +693,7 @@ Your choice. We hand off to the original CLI process — use your existing subsc
 
 **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/.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.
+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 7 days. Set `AGENTS_DISABLE_EVENT_LOG=1` to disable. See [Security & Privacy](#security--privacy) for details.
 
 ### Which platforms?
 

package/dist/commands/browser.js

@@ -1,12 +1,12 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { listProfiles, getProfile, createProfile, deleteProfile, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, } from '../lib/browser/profiles.js';
+import { listProfiles, getProfile, createProfile, deleteProfile, ensureDefaultBrowserProfile, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, } from '../lib/browser/profiles.js';
 import { findBrowserPath, getPortOccupant } from '../lib/browser/chrome.js';
 import { listProfileCacheDirs, removeProfileCache, listAllProfileSnapshots, } from '../lib/browser/runtime-state.js';
 import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
 import { discoverBrowserWsUrl, verifyBrowserIdentity } from '../lib/browser/cdp.js';
 import { parseTargetFilter } from '../lib/browser/service.js';
-import { sendIPCRequest } from '../lib/browser/ipc.js';
+import { BrowserDaemonNotRunningError, formatBrowserDaemonNotRunningError, sendIPCRequest, } from '../lib/browser/ipc.js';
 import { browserTaskPicker } from './browser-picker.js';
 import { isInteractiveTerminal } from './utils.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
@@ -59,8 +59,11 @@ export function registerBrowserCommand(program) {
       # 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
+      # Start a session — auto-picks the first installed Chromium-family browser
+      agents browser start
+
+      # Or pin to a specific profile
+      agents browser start --profile work
 
       # Drive the page
       agents browser navigate https://example.com
@@ -72,6 +75,12 @@ export function registerBrowserCommand(program) {
         notes: `
       Most agent workflows should use the 'browser' skill instead of raw subcommands.
       The skill wraps profile selection, snapshotting, and tunneling.
+
+      Browser support: Chromium-family only (Chrome, Comet, Chromium, Brave, Edge).
+      Safari and Firefox are not supported — they don't speak the Chrome DevTools
+      Protocol the way agents browser expects. On Windows, Edge is the default
+      because it's preinstalled. On macOS and Linux, Chrome is preferred when
+      installed; otherwise the first Chromium-family binary on disk wins.
     `,
     });
     registerProfilesCommands(browser);
@@ -346,7 +355,7 @@ function registerProfilesCommands(browser) {
             }
             else {
                 try {
-                    const { browser } = await discoverBrowserWsUrl(port);
+                    const { browser } = await discoverBrowserWsUrl(port, 'localhost', profile.name);
                     verifyBrowserIdentity(browser, profile.browser, port);
                     checks.push({
                         label: 'port',
@@ -437,39 +446,56 @@ function registerProfilesCommands(browser) {
 function registerTaskCommands(browser) {
     browser
         .command('start')
-        .description('Start a browser task with a profile')
-        .requiredOption('-p, --profile <name>', 'Browser profile to use')
+        .description('Start a browser task. Pass --profile <name>, or omit to auto-pick a Chromium-family browser already installed on this machine.')
+        .option('-p, --profile <name>', 'Browser profile to use (auto-picks from installed Chromium-family browsers if omitted)')
         .option(TASK_OPTION_FLAG, 'Task name (auto-generated if omitted)')
         .option('-e, --endpoint <name>', 'Endpoint preset (defaults to the profile\'s default)')
         .option('-u, --url <url>', 'Open URL in first tab')
+        .option('--no-skills', 'Skip auto-discovery of site-specific SKILL.md from ~/.agents/skills/browser/domain-skills/')
+        .option('--record', 'Start recording right after the tab opens (shorthand for `agents browser record start` as a follow-up)')
+        .option('--fps <n>', 'Recording frames per second (with --record; 1–30, default 5)', (v) => parseInt(v, 10))
+        .option('--duration <sec>', 'Recording duration cap in seconds (with --record; default 60)', (v) => parseInt(v, 10))
+        .option('--max-mb <mb>', 'Recording size cap in MB (with --record; default 25)', (v) => parseInt(v, 10))
         .action(async (opts) => {
+        let profileName = opts.profile;
+        if (!profileName) {
+            try {
+                const detected = await ensureDefaultBrowserProfile();
+                profileName = detected.name;
+            }
+            catch (err) {
+                console.error(err instanceof Error ? err.message : String(err));
+                process.exit(1);
+            }
+        }
         // Pre-check the profile locally so we fail fast with a helpful error
         // instead of round-tripping a generic "Profile not found" through the daemon.
-        const profile = await getProfile(opts.profile);
+        const profile = await getProfile(profileName);
         if (!profile) {
-            console.error(`Profile "${opts.profile}" not found.`);
+            console.error(`Profile "${profileName}" not found.`);
             const all = await listProfiles();
             if (all.length > 0) {
                 console.error(`Available profiles: ${all.map((p) => p.name).join(', ')}`);
             }
-            console.error(`Create one with: agents browser profiles create ${opts.profile} --browser <chrome|comet|chromium|brave|edge|custom>`);
+            console.error(`Create one with: agents browser profiles create ${profileName} --browser <chrome|comet|chromium|brave|edge|custom>`);
             process.exit(1);
         }
         // Pre-check the endpoint name too — same fail-fast rationale.
         if (opts.endpoint) {
             const presets = getEndpointPresets(profile);
             if (!presets[opts.endpoint]) {
-                console.error(`Endpoint "${opts.endpoint}" not found on profile "${opts.profile}". ` +
+                console.error(`Endpoint "${opts.endpoint}" not found on profile "${profileName}". ` +
                     `Available: ${Object.keys(presets).join(', ')}`);
                 process.exit(1);
             }
         }
         const response = await sendIPCRequest({
             action: 'start',
-            profile: opts.profile,
+            profile: profileName,
             taskName: opts.task,
             url: opts.url,
             endpoint: opts.endpoint,
+            skipDomainSkill: opts.skills === false,
         });
         if (!response.ok) {
             console.error(response.error);
@@ -488,6 +514,36 @@ function registerTaskCommands(browser) {
         }
         console.error(`Tip: export AGENTS_BROWSER_TASK=${response.task}`);
         console.error('Try: agents browser screenshot | agents browser console --level error');
+        // Surface the matched domain-skill (if any) so an agent driving the
+        // task picks up site-specific selectors and gotchas before it starts
+        // clicking. Header is recognizable so an agent parsing the stream can
+        // extract the skill content; suffix repeats the skill name for greps.
+        if (response.skill) {
+            console.error('');
+            console.error(`--- domain-skill: ${response.skill.name} (${response.skill.hostname}) ---`);
+            console.error(response.skill.content);
+            console.error(`--- end domain-skill: ${response.skill.name} ---`);
+        }
+        // --record convenience: fire record-start right after the tab opens so
+        // the user gets a single-command capture flow. Failures here are
+        // reported but don't fail the start — the task is already running.
+        if (opts.record) {
+            const recordResponse = await sendIPCRequest({
+                action: 'record-start',
+                task: response.task,
+                tabId: response.tabId,
+                fps: opts.fps,
+                duration: opts.duration,
+                maxMb: opts.maxMb,
+            });
+            if (!recordResponse.ok) {
+                console.error(`Recording failed to start: ${recordResponse.error}`);
+            }
+            else {
+                console.error(`Recording at ${recordResponse.fps} fps (cap ${recordResponse.durationCapSec}s / ${recordResponse.maxMb} MB) -> ${recordResponse.path}`);
+                console.error('Stop with: agents browser record stop');
+            }
+        }
     });
     browser
         .command('done')
@@ -798,10 +854,26 @@ function registerTaskCommands(browser) {
         .option('-p, --profile <name>', 'Filter by profile')
         .option('--json', 'Output machine-readable JSON')
         .action(async (opts) => {
-        const response = await sendIPCRequest({
-            action: 'status',
-            profile: opts.profile,
-        });
+        let response;
+        try {
+            response = await sendIPCRequest({
+                action: 'status',
+                profile: opts.profile,
+            }, { autoStartDaemon: false });
+        }
+        catch (err) {
+            if (err instanceof BrowserDaemonNotRunningError) {
+                const message = formatBrowserDaemonNotRunningError();
+                if (opts.json) {
+                    console.log(JSON.stringify({ ok: false, error: message }));
+                }
+                else {
+                    console.error(message);
+                }
+                process.exit(1);
+            }
+            throw err;
+        }
         if (!response.ok) {
             if (opts.json) {
                 console.log(JSON.stringify({ ok: false, error: response.error }));

package/dist/commands/cli.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `agents cli` — manage declarative CLI binary installs.
+ *
+ * Each entry under <repo>/cli/<name>.yaml declares a CLI tool the user wants on
+ * the host PATH (e.g. higgsfield, gh, glab). On a fresh machine `agents cli
+ * install` runs the first install method whose package manager is available
+ * (npm > brew > script > binary, in declared order).
+ *
+ * This is a sibling to `agents mcp` but one layer down: MCP wires servers into
+ * agent configs; CLI puts binaries on the user's normal PATH. CLI manifests are
+ * NOT copied into per-agent version homes — they are global to the user.
+ */
+import type { Command } from 'commander';
+export declare function registerCliCommands(program: Command): void;