Dispatch

Orchestrating agents with ccmux invoke

One uniform CLI launches and observes every harness the same way (claude, codex, cursor, opencode, pi, omp, gemini, plus custom agents). This skill is the mechanics; the agent-per-task policy comes from the user's prompt. ccmux never runs a model itself, so digesting a worker's output is your job, and the discipline that keeps an orchestration tractable is controlling how much each worker hands back. A single quick turn needs none of the machinery below (one ccmux invoke <agent> "..." suffices), and work faster to do yourself should stay yours: every invoke pays a 5-15s cold start.

invoke vs spawn: which tool

The test is who consumes the output. invoke returns a discrete result you thread into the next step (final turn on stdout, exit code, list/result/cancel); you consume it. spawn opens a persistent interactive tmux pane (no 30-min ceiling) and returns a paneId, not a result; its output is terminal scrollback consumed by a human at the pane. Reach for spawn only when the deliverable is a live session: a job that exceeds invoke's headless envelope (too long, or wedges headless on interactive approval) and a human will supervise, a task you judge wants human eyes (launch it, tell the user, stop), or workspace setup.

# Launch a live pane for the user, then stop. Do NOT poll or drive it.
ccmux spawn codex --cwd /path/to/repo --prompt "Long refactor: <brief>"
ccmux spawn claude --issue 163 --detach          # worktree issue-163-<slug>, prompt seeded from the issue
ccmux spawn codex --pr 155 --detach              # worktree on the PR's branch
ccmux spawn --worktree fix-flicker --model opus  # named worktree; the agent's own model flag

--issue <n> / --pr <n> cut a worktree from GitHub (via gh) and seed the prompt; --worktree [name] cuts one from the current branch (name derived from --prompt if omitted). Pass --detach when dispatching so the user's view stays put. The new window is named after the worktree, else the agent, so a batch of spawns is tellable apart in tmux. --model <name> maps onto each built-in's model flag and is refused for agents without a known one.

Do not drive a spawned pane as a worker (spawn -> ccmux send -> poll -> ccmux screen -> parse scrollback). It is a brittle scrape loop: no completion signal, render races, and an answer buried in terminal chrome. For multi-turn continuity use invoke's --session (see the session-resume gotcha), or fold prior context into the next invoke.

Mental model: two patterns, one fan-out trick

Fan-out + join is your own parallel tool calls; there is no batch primitive.

• Small N, all quick: N block-and-wait invokes as N separate Bash tool calls in one assistant turn (not N $(...) lines in one script, which run serially). Their return is the join, but each call holds a slot for its whole runtime, and on a harness that serializes tool calls they won't actually overlap.
• Large N, or long/uneven runtimes: fire each with --id, then join. See "Fire-and-poll" for the three join shapes.

The daemon caps concurrency at 16 in-flight invokes; beyond that, new invokes are rejected (see "Handling failures").

Prerequisites

• ccmux on PATH; ccmux invoke auto-starts the daemon (ccmux daemon status confirms).
• Claude as a worker requires its hooks (ccmux setup --agent claude); without them the invoke fails fast with exit 3 (hooks_missing). Subprocess agents (codex/cursor/opencode/pi/omp/gemini) need no hooks for invoke.
• There is no ccmux agents command to enumerate invokable agents. Built-ins: claude, codex, cursor, opencode, pi, omp, gemini; custom agents are whatever the user defined in ~/.config/ccmux/ccmux.json.

Generating invocation ids

--id must match ^inv_[A-Za-z0-9]{4,32}$ (the literal inv_ then 4-32 letters/digits; no dashes, underscores, or dots). Prefer readable task-scoped names (inv_planauth, inv_search1) so you recognize them in list; for guaranteed uniqueness use id="inv_$(openssl rand -hex 6)" (raw uuidgen output has dashes and fails the pattern). Reusing an id whose invoke already finished is allowed (newest-wins); reusing one still in flight is rejected (agent_error, message invocationId already in flight), so mint a fresh id.

Block-and-wait (quick tasks)

# Capture the worker's final turn directly. stdout has NO trailing newline.
plan=$(ccmux invoke claude "Plan, in 5 concise bullets, how to add a --dry-run flag to the importer.")

Exit 0 on success with the response on stdout; on failure, a message on stderr and a non-zero exit (table below). Keep responses small by telling the worker to be brief ("answer in <=5 bullets", "just the code, no prose"); that is the cheapest output control.

Fire-and-poll (long or many tasks)

Start each invoke without blocking your own progress, then join when it finishes. Three join shapes; pick the first your environment supports:

1. Push (best): background the blocking invoke as a harness job (e.g. Claude Code's Bash run_in_background). The harness wakes you on completion; you never poll.
2. wait on the client PID, when one shell stays alive for the whole run.
3. Poll the store, race-safely, when neither fits.

Join, best (push): background the blocking invoke

# Background the BLOCKING invoke via your harness's background-job mechanism
# (e.g. Bash run_in_background), NOT a shell `&`, and no redirect-detach needed:
# a blocking invoke returns the worker's output inline when it finishes.
ccmux invoke codex "Implement the --dry-run flag end to end. Report a concise summary." \
  --id inv_implflag --cwd /path/to/repo --timeout 1800000

Then stop; the backgrounded job's captured stdout is the worker's result. Set --id anyway so you can still cancel/result it by name. For a fan-out, background N such jobs; the harness's per-job completion notification is the join, no polling at all. (The push comes from your harness: the daemon's SSE events feed the ccmux TUI, and there is no CLI wait/notify primitive.)

The other two joins: wait and the race-safe poll

No background-job mechanism in your harness? The wait join and the race-safe store poll, plus their traps (the store-admission race and the long-foreground-shell kill), are in references/joins.md. Read it before writing any poll loop; the naive loop breaks in ways that look like worker failures but aren't.

Reading a worker's output: inline vs result

• The inline final turn is usually all you need; keep it small with a brevity prompt.
• result <id> exits 0 with the full output, 2 if no longer available, 1 on transport error / malformed id. It includes the agent's own stderr chrome (banners, prompts), so scan for the relevant part.
• Claude is the exception. A Claude invoke drives an interactive tmux session with no stdout buffer and writes no result file (result on a claude id always exits 2). A Claude worker's only output is the inline stdout, so never skip the redirect when backgrounding a Claude invoke, and do not poll result for it.

Controlling output size

You hold every worker's output in your own context; ccmux will not summarize for you. Prompt for brevity first ("summarize your changes in <=5 bullets"), and when you must capture a big result but only need the gist, pipe it through a cheap worker:

ccmux invoke result inv_bigjob | ccmux invoke claude "Summarize this in 3 bullets:"

Handling failures

Read the outcome from the exit code (block-and-wait) or the status + kind fields (list --json). Never regex the human-format rows.

status in list --json is running | succeeded | failed | cancelled; on failed, kind carries the same values as the exit table (a timeout reads status: "failed", kind: "timeout"). cancelled is first-class, distinct from failed, so your own cancels never read as failures.