/multi-agents

name: multi-agents
description: Hand a coding task to a team of coding agents (Claude Code, Codex) that work in isolated git worktrees and return a patch plus a cost record. Use for hard or ambiguous tasks, when you want a second opinion from the other CLI, or to compare two CLIs on the same task. Not for small edits you can finish yourself.

Hand a task to a team

`multi-agents` runs a team of coding agents on a git repository and returns **one patch and an itemized record** (tokens, cost, seconds per agent call). Each worker gets its own git worktree, so your working tree is untouched until you apply the patch.

When to use a team

Use it when a second agent is worth the extra minutes and cost:

• the task is hard, ambiguous, or you already failed at it once;
• the user wants a second opinion, or a patch checked by a different model;
• the user wants to compare Claude Code and Codex on the same task.

Do not use it for small edits, questions, or anything you can finish quickly yourself. A team costs real money and takes minutes. Say so when you start one.

Pick a spec

`H` is a harness with an optional model: `claude`, `codex`, `claude@haiku`, `codex@gpt-6-luna`.

| Spec | Use it when | |---|---| | `solo:worker=H` | You only want the other CLI to try, or the other CLI is not installed. Cheapest. | | `review:coder=H,reviewer=H[,rounds=N]` | **Default.** One agent codes, another reviews the patch and sends feedback; the best-scoring patch wins. | | `best:workers=H+H[+H...][,judge=H]` | The user wants a comparison: workers run in parallel and a judge picks the best patch. | | `plan:planner=H,workers=H[+H...][,integrator=H][,max_tasks=N][,replans=N][,reviewer=H][,rounds=N]` | A large task that splits into independent parts: a planner splits it, workers solve the parts in parallel, an integrator merges. Failed or empty subtasks go back to the planner once (`replans=0` turns that off); `reviewer=H` makes every subtask a coder ⇄ reviewer loop (`rounds` needs it; `check` is not allowed here). Use it only when the user asks or the task clearly splits. |

**Default (cheap):** the coder is the *other* CLI than the one you are running in, so the patch is an independent attempt. The reviewer is *your own* CLI, which is certainly installed and logged in. Both use small models and two rounds:

• running in Claude Code: `review:coder=codex@gpt-6-luna,reviewer=claude@haiku,rounds=2`
• running in Codex: `review:coder=claude@haiku,reviewer=codex@gpt-6-luna,rounds=2`

If the other CLI is not installed (`command -v codex` / `command -v claude`), use `solo:worker=<your CLI>@<small model>` instead. Use larger models or `best:` only when the user asks or the task justifies the cost. If the user gives a spec, use it as written.

Add an objective check

If the project has a test, build or lint command, use its real invocation (from the README, CI config or Makefile; check that it runs here, do not guess) and pass it with `--check '<command>'`. The final patch is run through it in a fork and the record says whether it passed. The `check` harness can replace an LLM reviewer or judge, which makes the loop test-driven and cheaper:

review:coder=codex@gpt-6-luna,reviewer=check,rounds=2   --check 'pytest -q'

Three things make the check trustworthy:

• The fork starts at the base commit with the patch applied. It has none of your untracked

dependencies, and a virtualenv on `PATH` still points at the original checkout. Make the command self-contained, e.g. `--check 'python -m venv .venv && .venv/bin/pip install -q -e . pytest && .venv/bin/pytest -q'`.

• The check runs on whatever the agents left behind, including edited tests. Restore the tests

first: `--check 'git checkout HEAD -- tests && git clean -fdq tests && python3 -m unittest -q'`.

• `--timeout` bounds the check too; a timeout counts as a failure.

Cap the spend

`--max-cost USD` stops new agent runs once that much has been spent; the team then returns the patch it has so far. Use it when the user names a budget, and say what the cap means: runs already in flight finish, so the total can overshoot by their cost (parallel workers run side by side). An unpriced harness cannot be counted, so the command refuses to start a team with one and names it, unless you also pass `--allow-unpriced`, which counts its runs as $0 and leaves their spend outside the limit. Do not add `--allow-unpriced` on your own; tell the user instead. The summary ends with a `budget:` line (spend, limit, refused runs).

Run it

Run it from the repository the task is about, with the shell tool. Quote the task; put the whole task in it, since the workers do not see this conversation:

uvx --from multi-agent@latest multi-agents run \
  --repo . --timeout 600 --team '<spec>' '<task>'

Single-quote the task, and replace every `'` inside it with `'\''`. Task text often contains backticks or `$`, which a double-quoted shell argument would execute or expand. `--timeout 600` bounds each agent call to ten minutes.

Add `--check '<command>'` when you have one, and `--max-cost <usd>` when the user set a budget. Requirements: `uv`, `git`, and a logged-in `claude` and/or `codex` (the CLIs use their own login; no API keys are needed). The repository needs at least one commit; workers start from `HEAD`, so **uncommitted changes are not visible to them**. Tell the user if the tree is dirty.

The run needs network access (to fetch the CLI and for the worker CLIs), write access to `~/.cache/multi-agents` and `~/.cache/uv`, and permission to start `claude` and `codex`. If your shell is sandboxed or asks for approval, request that this one command run outside the sandbox. If it cannot run (no network, approval denied, a CLI is not logged in), **stop and tell the user why**. Never fall back to doing the task yourself under this skill: the user asked for a team.

A run takes one to several minutes. Run it in the background (or with the shell tool's longest t