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¶

Command	Current behavior
`parallel`	Create agent layouts, create a shared context file, collect outputs, or emit a template command
`browser`	Prepare browser automation tooling or launch supported browser automation endpoints
`add-config`	Scaffold AI config files, instructions, and optional shared `.ai` assets in a repository
`add-mcp`	Resolve MCP entries from StackOps catalogs and install them into agent configs
`run-prompt`	Run one prompt through a selected agent, with inline, file, or YAML-backed context
`run-interactive`	Launch an agent with reasonable defaults
`ask`	Ask a selected agent directly
`add-skill`	Add a supported skill into an agent directory

`parallel`¶

Current subcommands:

Command	Behavior
`create`	Build an agent layout file with prompt/context splitting and output paths
`create-context`	Ask one agent to persist a shared `context.md` for a job
`run-parallel`	Run a named parallel workflow from `parallel.yaml`, with `create` option overrides
`collect`	Concatenate collected agent material files into one output file
`make-template`	Print a starter template for fire-agent usage

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
--reasoning for codex, copilot, and pi agents; unsupported agents ignore it
--context or --context-path
--context-yaml-path plus --context-name
--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.

Examples:

agents run-prompt --agent codex --reasoning high --context-path ./context.md "inspect this repo"
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 --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 currently requires --agent and can optionally add private config files, instructions, shared .ai assets, VS Code tasks, and .gitignore entries. Pass --agent all to configure every supported agent, or pass a comma-separated list.

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

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, caveman, grill-me, last30days, agentops, 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, playwright-cli, chrome-devtools-mcp, or playwright-mcp. 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.

agents browser install-tech
agents browser install-tech --which playwright-cli
agents browser install-tech --which chrome-devtools-mcp
agents browser install-tech --which playwright-mcp
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-browser 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 temp profile under the system temp directory for profile-capable browsers; a profile name uses ~/data/browsers-profiles/<browser>/<profile>. 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 to launch background processes instead of tmux windows.

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

`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, caveman, grill-me, last30days, agentops, 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 stackops --scope local --backend s
agents add-skill agentops --scope local --backend stackops
agents add-skill grill-me --scope local
agents add-skill caveman --agent codex --scope local
agents add-skill caveman --agent github-copilot --scope global

Getting help¶

agents --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-browser --help

agents¶

Usage¶

Current top-level commands¶

parallel¶

Prompt-running commands¶

Repository and MCP helpers¶

Browser Automation¶

add-skill¶

Getting help¶

`parallel`¶

`add-skill`¶