CLI Subagents

These tools are your subagent tool. Use them the way you would use a built-in "spawn a subagent" tool: hand over a self-contained task, keep working, collect the result, check it. Each subagent runs in Claude Code, Codex, Antigravity or OpenCode with the parent's MCP servers and instructions. Same-CLI accounts also share its plugins, skills and settings. Choosing a pooled account and switching at a quota limit happen on their own. OpenCode uses the user's one profile and does not rotate accounts after a free-model limit.

In Claude Code: always start a relay agent

In Claude Code, start every CLI Subagents job with your Agent tool and one of the four relay agent types. This holds at every depth where delegation is allowed.

Don't run csa run, csa start or csa follow in your own shell, and don't call subagent_start. A job started that way never appears in the user's agent list, and your turn is blocked while you wait on it. A relay agent appears with its own color, the user can open it and watch every step the worker takes (commands, edits, messages, reasoning), and you get the usual notice when it finishes.

Agent tool:
  subagent_type: cli-subagents:cli-subagents-codex
  description: Sol 6.1 high · edit · fix the login test
  run_in_background: true
  prompt: |
    model=gpt-6.1-sol
    effort=high
    access=edit

    <the complete, self-contained task>

• Description: <model> · <access> · <task in a few words>. The user reads it to see what runs where.
• Prompt: option lines first, one per line (model=..., effort=..., access=read|edit, and only when needed account=NAME, cwd=PATH, timeout=SECONDS, override=USER_WORDS under the Limits rule below), then a blank line and the complete task written as below. access defaults to edit in the Claude relay and read in the Codex, Antigravity and OpenCode relays.
• Start it in the background and keep working. Don't poll or wait in a shell; the notice arrives when it finishes.
• Its final message is the worker's result, unchanged. If the worker asks something, the agent stops and tells you; answer with SendMessage to that agent and it passes the answer on. While the job runs, SendMessage "cancel" stops it and anything else goes to the worker as a follow-up, unchanged; the relay never answers it itself, whatever the text says. After the job has finished, SendMessage to the same relay continues the worker's conversation as a new job; the relay follows it and returns its result.

A relay shows the worker's messages, the notes it writes between steps, as its own messages, word for word and one after another, like the Codex app. Its first message names the relay's model and the worker's, read from their logs, and says when the worker runs another model or effort than the one asked for. Each csa follow call returns as soon as a new message is complete. Only the worker's final result comes back to you; the copied messages stay in the relay's view.

The relay gets a fresh absolute path from csa relay-path, writes the complete prompt with its host's file tool, then runs csa run --follow --window 180 --runtime <runtime> --relay-file <path>. csa validates the inbox file, reads UTF-8, deletes it and parses the same leading option lines as --relay -. Keep the blank separator before the task. Payload never appears in shell syntax, so its length and quotes cannot break a shell command. Answers and follow-ups use fresh files with csa message --relay-file and remain message text, even when they begin with key=value. Files are limited to 16 MiB; invalid files or options return an authenticated FAILED result. Claude uses Write in the csa home inbox with a narrow plugin permission hook. Codex and Antigravity use csa relay-path --workspace in the caller's writable workspace. csa writes a .gitignore containing * there before returning a payload path. Codex uses native apply_patch to write plain text; its line-ending normalization and final newline are acceptable. Keep quotes and Windows paths literal. Do not widen host permissions or fall back to embedding payload in a shell command if writing fails.

The MCP tools below work everywhere. In Codex, csa setup --host codex installs the same four relays as native agents (cli-subagents-codex and so on); start them with Codex's own subagent tool as the Codex note shows, and use the MCP tools there only when those agents are missing. In Antigravity, csa setup --host antigravity installs them as a companion plugin of subagents; start them as the Antigravity note shows. In Claude Code, too, use the MCP tools only when the relay agent types are missing.

The loop with the MCP tools

1. Start: subagent_start with a complete task (prompt), the project folder (cwd, absolute) and access (read for analysis and review, edit for changes). Claude workers on read get read-only tools (file reading, search, web) plus shell commands with read-only options, including git diff; a worker hook rejects writes, execution helpers and named secret paths. Start several jobs before waiting if the work is independent.
2. Wait: subagent_wait with the job IDs. It returns when a job finishes or a subagent sends a message or question. Call it again for the jobs still running.
3. Answer: if a result shows open_questions, reply with subagent_message and reply_to set to the question id. To give a running subagent new instructions, send subagent_message without reply_to. In Claude Code a hook also wakes an idle session when a job finishes or asks something, so you can end your turn after starting jobs.
4. Collect and check: finished jobs come back with outcome and result. success means the subagent finished. Collecting a result claims it and suppresses later automatic notifications. Explicit subagent_result or csa follow calls can return it again. Still read the diff, run the tests and confirm the files exist before relying on it.
5. Follow up: subagent_message to a finished job continues the same conversation as a new job.

Writing the task

The subagent can't see this conversation. State the goal, the files or folders involved, what it must not touch, decisions already made, how to verify the result, and what to report back. Point to files instead of pasting them.

Optional arguments: runtime (claude by default, codex, antigravity, opencode) when a specific agent or a second opinion from another vendor helps; model; effort; max_turns; timeout_seconds (default 1800); resume_job to continue an earlier job's conversation; account to pin one account; add_dirs. Turn-limit support depends on the runtime.

access: "full" skips the CLI's own permission checks. Use it only when the user asked for that.

Codex and Antigravity workers have their own web search and page reading, which reach sites such as Reddit that block other tools, so they suit web research. Antigravity workers find YouTube videos and read their title and description, but can't watch them or read transcripts.

When to pick OpenCode

Use opencode for personal projects when the user wants OpenCode or a free model and their vendor rules allow it. csa discovers OpenCode v2 (@opencode/cli) when opencode is on PATH. A missing binary adds no setup task; [opencode] enabled = false disables it. OpenCode is a worker only, not a supported host.

Omit model to keep the user's OpenCode model. When none is configured, csa uses opencode/deepseek-v4.1-flash-free. An unavailable model fails the job; csa never lets OpenCode fall back to another model. effort becomes the model's variant (low, high or max on the default model); an effort the model lacks fails with a clear message. Free models are for personal projects only. The provider says DeepSeek does not train on your data, but Anomaly's unpaid-content terms still apply. Big Pickle, MiMo and Flint may use collected data and the Nemotron endpoints log it; csa never defaults to them and blocks them unless the user chose that model. Free limits are per IP per day and reset at UTC midnight. On provider.free-limit, stop without account rotation; wait for the reset or follow the user's fallback rules.

On supported Windows, OpenCode edit workers' shell commands run in fresh MXC containers (workspace writes, protected git/agent settings, no Git Bash). Fixed-rule builds/tests have no internet egress, with host loopback allowed; reviewed commands get egress. OpenCode, its file tools, the gate and reviewer chain stay on the host with normal state and logins. File tools rely on gate paths. read allows workspace reads/list/search and no commands, so its file reads have no OS containment. edit adds workspace edits and ordinary read-only commands. The default reviewers are Claude Haiku then Gemini Flash through agy; configure [review] or [[opencode.reviewers]]. Reviewers off or unable to decide means denial. Both levels deny Code Mode execute, subagents and MCP servers other than csa-parent, send web fetch/search to review and ignore project OpenCode config. full uses --auto without gate or sandbox and requires the user's explicit request. See OpenCode and Sandbox, including Fence for macOS/Linux.

Limits

Limits are enforced by csa. If a start is refused, follow the suggestion in the message; don't count quotas yourself.

Accounts marked explicit_only require an explicit account; automatic selection and failover skip them. All account spend caps apply together, including rolling windows, and cannot be bypassed with override; a budget outcome stops without retry or failover, so follow its message or wait for room under every cap.

Never set override on your own judgment; use it only when the user asked for more jobs in this conversation, or confirmed after you warned them and told them how much of the 5-hour window is left. Use csa's reported usage and reset time; if the window is unknown, say so. Otherwise ask the user or use the home model.

Put the user's own words in override, for example the relay line override=user asked for 6 Codex agents, the override field on subagent_start, or --override "user asked for 6 Codex agents" on csa run or csa start. Empty values are rejected. This bypasses only csa's job caps, quota steps, usage ceiling, pool budgets and queueing. Account and pool cooldowns after real usage-limit errors, models, max_effort, login, depth and access still apply. Override jobs count toward later starts. The text is stored and shown in job lists, follow headers and status/result summaries. A new start needs its own override; a follow-up to a finished job does not inherit it.

Outcomes

Per host

Read the note for the CLI you are running in once: Claude Code, Codex or Antigravity. It covers how waiting works there and where to put new skills, MCP servers and instructions so every subagent shares them.

• Claude Code: subagent_wait can run for up to an hour; Claude Code moves it to the background and notifies you when it returns.
• Codex: waits end after 240 seconds; call subagent_wait again until the jobs finish.
• Antigravity: keep waits to a few minutes and call again.

What subagents get

Subagents in the same CLI as you load the same setup you have. Subagents in another CLI get a short note listing your instruction files and skill folders to read. Claude, Codex and OpenCode workers get message_parent (progress notes), ask_parent (a question; it waits for your answer) and check_parent_messages (follow-ups you send). OpenCode also receives instruction-file paths in its config and exposes the parent tools individually with codemode: false. Antigravity workers get them only with an effective account cap of exactly 1 and a managed worker folder; the primary file-login fallback has no parent channel. See Gemini messages. Subagents can't start subagents of their own. Tools built into the Claude desktop app itself (its browser or terminal panes, for example) aren't available to them. Plugins from another CLI are not translated into OpenCode plugins.

Never put secrets or credentials in a prompt.