agents¶

agents manages StackOps's AI-agent scaffolding, prompt execution, MCP catalog installs, and parallel multi-agent job files.

Usage¶

agents [OPTIONS] COMMAND [ARGS]...

Current top-level commands¶

iter¶

iter supports only the latest Herdr CLI and server; each command validates the live herdr api snapshot shape itself. Each maintenance command accepts exactly one targeting mode: an explicit stable WORKSPACE_ID, --all, or --interactive/-I. Use --dry-run/-n to preview close or clean. The interactive TV picker previews the live status and close plan for status and close; these commands locate each workspace's exact .ai/agent-ops/iterations/<slug>/run.json from Herdr agent cwd ancestry and do not require Git or the caller's cwd. close removes only quiet old tabs whose current handoff receipt still matches every stable Herdr identifier. clean is records-tree-local because inactive runs no longer exist in Herdr; run it anywhere beneath the project containing the .ai/agent-ops tree to clean. The obsolete polling budget tracker was removed because it could terminate a working successor.

agents iter status --all
agents iter status -I
agents iter close w1 --dry-run
agents iter close --all --dry-run
agents iter close -I
agents iter clean --all --dry-run
agents iter clean -I -n

clean¶

clean [DIRECTORY] discovers direct child Git repositories and removes each repository's .ai directory. Pass --recursive/-r to search nested repositories. The removal is immediate, so point the command at the intended repository root.

agents clean ~/code
agents clean ~/code --recursive

doctor¶

doctor [AGENT] reports agent health and resource provenance. AGENT defaults to all; use --directory/-d to inspect another project and --resource/-r to select comma-separated configuration, mcp, plugin, skill, or instructions resources.

agents doctor
agents doctor codex --directory . --resource plugin,skill,instructions

second-brain¶

second-brain config creates ~/code/agents/second-brain and installs its starter AGENTS.md when that file does not already exist. Existing instructions are preserved.

agents second-brain config

parallel¶

Current subcommands:

agents parallel create currently accepts the main workflow controls: --agent, --model, --reasoning, --provider, --host, --backend, --context or --context-path, --prompt or --prompt-path, --prompt-name, --job-name, --agent-load, --stagger-max, --separator, --joined-prompt-context, --run, --agents-dir, --output-path, --save-as-yaml, and --interactive. --backend defaults to tmux; use --backend herdr when --run should launch the generated layout through Herdr, or --backend aoe when it should launch each generated agent script as an Agent of Empires session. --save-as-yaml writes or updates .stackops/agents/parallel.yaml using the resolved job name as the top-level entry key.

agents parallel run-parallel reads flat top-level named entries from parallel.yaml. By default it searches the repo file first, then StackOps private/public/library locations. Use --source, -S to choose lookup locations, --yaml-path for an explicit file, --show-format to print the standard, --edit to open the YAML, and --add-entry to append a template entry before editing. Every create option can be overridden on the command line.

Standard parallel.yaml shape:

entryExample:
  agent: codex
  model: null
  reasoning: null
  provider: null
  host: local
  backend: tmux
  context: null
  context_path: null
  separator: "\n@-@\n"
  agent_load: 3
  stagger_max: 3.0
  prompt: null
  prompt_path: null
  prompt_name: null
  job_name: AI_Agents
  join_prompt_and_context: false
  run: false
  output_path: null
  agents_dir: null
  interactive: false

Examples:

agents parallel --help
agents parallel create --help
agents parallel create --agent codex --reasoning high --context-path ./.ai/agents/docs/context.md --prompt-path ./.ai/prompts/update.md --job-name updateDocs
agents parallel create --agent codex --reasoning high --context-path ./.ai/agents/docs/context.md --prompt-path ./.ai/prompts/update.md --job-name updateDocs --save-as-yaml
agents parallel create --agent codex --backend herdr --run --context-path ./.ai/agents/docs/context.md --prompt-path ./.ai/prompts/update.md --job-name updateDocsHerdr
agents parallel create --agent codex --backend aoe --run --context-path ./.ai/agents/docs/context.md --prompt-path ./.ai/prompts/update.md --job-name updateDocsAoe
agents parallel create --agent copilot --reasoning high --context-path ./.ai/agents/docs/context.md --prompt-path ./.ai/prompts/update.md --job-name updateDocsCopilot
agents parallel create --agent pi --provider openai --model gpt-5.4 --reasoning high --context-path ./.ai/agents/docs/context.md --prompt-path ./.ai/prompts/update.md --job-name updateDocsPi
agents parallel run-parallel default -S repo --agent-load 5
agents parallel run-parallel docs_update --yaml-path ./.ai/parallel.yaml --agent pi --reasoning high
agents parallel create-context --job-name updateDocs "Collect the repo context for this doc task"
agents parallel collect ./.ai/agents/updateDocs ./tmp/materials.txt

Prompt-running commands¶

run-prompt is the structured workflow entrypoint. It supports:

• --agent
• --interactive/-i to start the selected agent's native chat with the prepared prompt and continue with follow-up messages
• --reasoning for codex, copilot, and pi agents; unsupported agents ignore it
• --context or --context-path
• --context-yaml-path plus --context-name
• --skill/-k to reference one supported agent skill (same catalog as agents add-skill) on the fly: the prompt file tells the agent to read the skill's SKILL.md from its source repository and follow it; the skill is never installed. Pass an empty value (--skill "") to pick the skill interactively
• --source, -s to choose catalog locations for context YAML lookup: all, repo, private, public, or library
• --show-format and --edit for prompts-YAML guidance and editing
• free-form prompt parts after --; option-looking tokens after the delimiter are prompt text, not StackOps flags

For run-prompt, --agent defaults to codex. --source repo or -s repo resolves to <git-root>/.stackops/agents/prompts.yaml. Shell metacharacters such as |, >, $, and * are still interpreted by your shell before StackOps receives the prompt.

Interactive mode sends the same prompt, context, and skill reference as the first message, then leaves the agent's chat open. It supports agy, cursor-agent, claude, qwen, copilot, codex, opencode, auggie, droid, and pi. Other agents report an error before preparing context. Reasoning, Second Brain, and sandbox options still apply; container sandboxes allocate a terminal. Without --interactive, the existing prompt-running behavior is unchanged.

Context selection works the same in either mode. Pass --context "" to run without context or a YAML picker. Use agents i to open an empty chat without preparing a prompt.

Examples:

agents run-prompt --agent codex --reasoning high --context-path ./context.md "inspect this repo"
agents r -i --context-path ./context.md "inspect this repo"
agents r --interactive --agent copilot --context "" "help me debug this"
agents run-prompt --agent codex --reasoning high --context-path ./context.md -- inspect this repo --include-hidden
agents run-prompt --agent copilot --reasoning high --context-path ./context.md "inspect this repo"
agents run-prompt --agent copilot --context-name docs.cli -s all "update the assigned docs"
agents run-prompt --agent agy --context-path ./context.md "inspect this repo"
agents run-prompt --agent pi --reasoning high --context-path ./context.md "inspect this repo"
agents run-prompt --agent codex --skill caveman --context-path ./context.md "compress your replies"
agents run-prompt --show-format

run-interactive launches an agent directly with sensible defaults. Current options:

• --agent/-a accepts codex/x, copilot/c, pi/p, or opencode/omp/o
• --caveman/-c starts the session with the caveman wenyan-full prompt
• --headroom/-h launches codex or copilot through headroom

Examples:

agents run-interactive --agent codex
agents run-interactive --agent copilot --caveman
agents run-interactive --agent codex --caveman --headroom

ask is the lighter-weight direct path. Current behavior to keep in mind:

• default agent is codex
• --reasoning accepts n, l, m, h, x
• that shortcut is only supported for codex, copilot, and pi
• --file-prompt appends the file contents into the final prompt with explicit file boundary markers
• --quiet skips the Rich preflight summary and streams agent output directly

Examples:

agents ask --agent codex --reasoning h "inspect the repo"
agents ask --agent copilot --reasoning m "summarize the current module"
agents ask --agent agy "inspect the repo"
agents ask --agent pi --reasoning h "inspect the repo"
agents ask "summarize this file" --file-prompt ./README.md
agents ask --quiet "summarize the current directory"

Repository and MCP helpers¶

add-config requires an agent argument and copies the latest Agent-Ops skill bundled with StackOps into .agents/skills/agent-ops by default. Pass --no-agent-ops-skill/-A to skip that copy. It can also add private config files, instructions, shared .ai assets, VS Code tasks, and .gitignore entries. Pass all to configure every supported agent, or pass a comma-separated list. Pi and OMP configurations include their native ten-attempt exponential retry policies for transient API failures.

agents add-config all --root .
agents add-config codex,copilot,agy,pi,omp --root . --include-scripts --add-gitignore
agents add-config codex --root . -A

add-mcp resolves names from StackOps MCP catalogs and installs them for one or more agents. It also accepts known agent-skill names as a compatibility path; those are installed through the skills CLI and are not written to MCP config. Notes:

• --scope local installs into the enclosing git repository; when run from a multi-repo workspace root, it installs into that workspace directory
• --source, -S selects catalog locations: all, repo, private, public, or library
• --edit opens the catalog files and exits immediately if no MCP names were provided
• copilot means GitHub Copilot CLI. Local MCP config is written to .mcp.json; global MCP config is written to $COPILOT_HOME/mcp-config.json when COPILOT_HOME is set, otherwise ~/.copilot/mcp-config.json
• agy means Google Antigravity CLI. Local MCP config is written to .agents/mcp_config.json; global MCP config is written to ~/.gemini/antigravity-cli/mcp_config.json
• oz means Warp Oz CLI. Local MCP config is written to .warp/mcp.json in Oz's direct --mcp file shape, and StackOps passes that file to oz agent run --mcp when it exists.
• pi local MCP config is written to .pi/mcp.json; global MCP config is written to ~/.pi/agent/mcp.json
• agent-browser, agent-skills, archify, caveman, grill-with-docs, last30days, agent-ops, and stackops are skills/plugins, not MCP servers; those names delegate to the same installer as add-skill
• PostgreSQL is available as postgres; replace the generated DATABASE_URI value before use

For add-mcp, --source repo or -S repo resolves to <git-root>/.stackops/mcp.json.

agents add-mcp --help
agents add-mcp postgres,filesystem --agent codex,copilot,agy,oz,pi --scope local
agents add-mcp caveman --agent codex --scope local
agents add-mcp --edit -S library

Browser Automation¶

agents browser install-tech prepares browser automation tooling. The default is the direct agent-browser CLI and Vercel skill. --which accepts agent-browser, browser-use, pinchtab, playwright-cli, chrome-devtools-mcp, playwright-mcp, or omp. browser-use installs or upgrades the official Python CLI with uv on Python 3.12 and registers its bundled skill for the selected agent. pinchtab installs the current release binary and its official agent skill. playwright-cli installs the official Playwright agent CLI and skills. The MCP entries write StackOps guide/config files under ~/code/agents/browser/mcp/...; CDP and extension MCP entries are cataloged too, and must be paired with browsers launched from StackOps custom profiles. omp (Oh My Pi) is an agent with a built-in Puppeteer browser tool; the entry installs it from the installer catalog, writes a guide and a browser.cdpUrl config overlay under ~/code/agents/browser/omp/ for attaching to a StackOps CDP endpoint, and does not use --agent.

agents browser install-tech
agents browser install-tech --which browser-use
agents browser install-tech --which pinchtab
agents browser install-tech --which playwright-cli
agents browser install-tech --which chrome-devtools-mcp
agents browser install-tech --which playwright-mcp
agents browser install-tech --which omp
agents add-mcp chrome-devtools --agent codex --scope local
agents add-mcp chrome-devtools-browser-url --agent codex --scope local
agents add-mcp playwright --agent codex --scope local
agents add-mcp playwright-cdp --agent codex --scope local

agents browser launch launches Chrome, Brave, Edge, Firefox, or Safari automation endpoints. Chromium browsers use CDP with an isolated profile; Firefox uses WebDriver BiDi; Safari uses safaridriver. The default port is 9331; pass --port 9222 when using the shipped CDP MCP catalog entries without editing them. Omitting --profile uses a port-scoped profile under the system temp directory for profile-capable browsers; a profile name uses ~/data/browsers-profiles/<browser>/<profile>. Pass --tmp/-t with --profile to copy that profile to <profile>/.tmp/<random-alias> and launch the copy. By default, StackOps runs browser endpoints in one stackops-browser tmux session with qualified windows such as chrome-profile-agent-browser-p9331-endpoint; --lan/-l adds a matching relay window and exposes the requested port through a StackOps relay on 0.0.0.0. Pass --detached/-d to launch background processes instead of tmux windows.

agents browser launch --browser chrome --port 9331 --profile agent-browser
agents browser launch --browser edge --port 9331 --profile agent-browser
agents browser launch --browser chrome --profile agent-browser --tmp
agents browser launch --browser chrome --port 9222 --profile playwright-mcp
agents browser launch --browser chrome --port 9331 --lan
agents browser launch --browser chrome --port 9331 --profile agent-browser -d
agents browser status
agent-browser connect http://OTHER_COMPUTER_IP:9331

agents browser close closes StackOps-tracked launches selected in exactly one of two ways: --port (default 9331) closes one endpoint, while --profile closes the comma-separated saved profiles under ~/data/browsers-profiles/<browser>/<profile>, including their --tmp copies. --profile requires a profile-capable browser, so Safari must use --port. Both modes cover tmux and detached launches, leave other ports and profiles, other browsers, and browser sessions not managed by StackOps untouched, and succeed without changing anything when nothing matching is active.

agents browser batch-launch launches every saved profile under ~/data/browsers-profiles/<browser>/ for the browser selected with --browser. Its --port-start/--port/-p base defaults to 60000. Profiles named pN use port-start + N, so p1 uses 60001, p2 uses 60002, and so on by default. Other profile names use the next unreserved port above the base. Use --max-profiles/--max/-n to cap the launch count; StackOps launches the requested count or the number available, whichever is smaller. The command prints one compact table with each profile, IP, port, state, and tmux window or process ID. It supports the same --lan and --detached launch modes as launch; Safari is excluded because it does not support custom profiles.

agents browser batch-close closes every StackOps-tracked launch for a saved profile or one of its --tmp copies for the selected browser, including both tmux and detached launches. It leaves port-scoped profiles, other browsers, and browser sessions not managed by StackOps untouched. Running it when no matching launches are active succeeds without changing anything.

agents browser close --browser chrome --port 9331
agents browser close --browser chrome --profile p1,p2
agents browser batch-launch --browser chrome
agents browser L --browser firefox -n 4 --lan
agents browser batch-launch --browser brave --port-start 61000 --detached
agents browser batch-close --browser brave

agents browser declutter removes rebuildable data from a named profile (or from every saved profile of the browser with --all) after confirming that the selected browser is closed. Chrome, Brave, and Edge cleanup includes downloaded on-device AI models (including OptGuideOnDeviceModel) plus HTTP, code, GPU, shader, and extension-download caches. Firefox cleanup includes its disk, startup, and shader caches. Cookies, history, passwords, extensions, sessions, service-worker data, IndexedDB, and local storage are preserved. The command reports the recovered and remaining profile sizes in MiB.

agents browser replicate COUNT copies a closed source profile to p1 through pCOUNT. Chrome is the default browser and base is the default source profile. All destination paths are checked before copying; existing copies are refused unless --overwrite is passed, which deletes each existing destination completely before recopying. Both profile-maintenance commands use the same ~/data/browsers-profiles/<browser>/<profile> layout on Windows, macOS, and Linux. They support Chrome, Brave, Edge, and Firefox; Safari is excluded because safaridriver does not support StackOps custom profiles.

agents browser declutter --profile example-copy
agents browser declutter --browser firefox --all
agents browser replicate 4
agents browser replicate 3 --browser brave --profile example-copy
agents browser replicate 5 --overwrite

add-skill¶

add-skill uses the StackOps backend by default, copying bundled skills directly into <repo-root>/.agents/skills/<skill> for local installs. If the StackOps backend cannot handle the request, it reports the reason and falls back to the existing bunx skills@latest add path. Use --backend bunx to run the upstream skills CLI directly, or --backend npx to run npx skills@latest add instead. The shipped source aliases are agent-browser, agent-skills, archify, caveman, grill-with-docs, last30days, agent-ops, and stackops; omitting the skill name opens the fuzzy picker over those aliases. Unknown skill names exit with an error instead of searching for alternatives. --agent is passed through to the skills CLI without StackOps mapping for bunx/npx; the StackOps backend installs into the shared repo-local skill directory. --directory chooses the install root and defaults to the current directory. Use agents browser install-tech for the browser-specific installer and MCP setup notes.

agents add-skill --scope local
agents add-skill stackops --agent codex --scope local
agents add-skill agent-skills --agent codex --scope global
agents add-skill last30days --agent codex --scope global --backend npx
agents add-skill archify --agent codex --scope global --backend npx
agents add-skill stackops --scope local --backend s
agents add-skill agent-ops --scope local --backend stackops
agents add-skill grill-with-docs --scope local
agents add-skill caveman --agent codex --scope local
agents add-skill caveman --agent github-copilot --scope global

Getting help¶

agents --help
agents clean --help
agents doctor --help
agents second-brain --help
agents parallel --help
agents add-config --help
agents add-mcp --help
agents run-prompt --help
agents run-interactive --help
agents ask --help
agents add-skill --help
agents browser install-tech --help
agents browser launch --help
agents browser close --help
agents browser batch-launch --help
agents browser batch-close --help
agents browser declutter --help
agents browser replicate --help