Run agents in parallel

Ask for it

You do not start sub-agents with a command; you ask in plain words. In Operate, Codewhale does this on its own for independent steps. In Work, say what you want split up:

Use three explore agents in parallel: one maps the auth code,
one maps the billing code, one lists the tests that cover both.
Then summarize what would break if we changed the session format.

Each sub-agent starts in the background and reports back when it finishes. Your composer stays free, and the parent turn picks up the results.

Pick a role

A role is the stance a sub-agent takes. Name one in your request, or let Codewhale choose. A sub-agent never gets more permission than your session has.

general

Does whatever the brief says; may edit and run commands. The default.

explore

Read-only. Maps the relevant code fast — “find every caller of this function.”

planner

Designs an approach without changing anything.

reviewer

Reads and grades a change, with a severity for each finding.

implement

Lands one specific change with the smallest edit.

test

Runs tests and checks, then reports pass or fail. Does not edit code.

advisor

Short, careful second opinion on a judgment call. No commands.

custom

Only the tools you list, for tightly limited jobs.

To give a role a specific model every time, save it with /fleet setup — see Run a workflow.

Keep parallel edits apart

When two sub-agents would edit the same repository, ask for each to work in its own worktree. Codewhale creates a fresh git worktree and branch for that agent beside your repository, under .codewhale-worktrees/, so your checkout stays clean until you merge.

A worktree is isolation, not permission: an agent that should write still needs a writing role and the paths it may change. Two agents that claim the same files are stopped before either one edits anything.

Watch and answer them

/subagents

/subagents (the same view as /fleet workers) lists the agents attached to this session and what each one is doing. Select one to read its transcript.

Sub-agents follow your approval setting. In Ask, a call that needs approval appears in your session as a normal prompt while the agent waits. In Auto-Review, each held call gets the same independent review, and nothing prompts you. Every decision you did not make yourself is written to the agent's transcript.

Know the limits

Running at once

64 by default. Set max_subagents (up to 128) in ~/.codewhale/config.toml.

Queued plus running

Up to 1,024; extra launches wait for a slot.

Nesting

A sub-agent may start its own, three levels deep by default, never more than eight.

These are ceilings, not targets. A few well-scoped agents with one clear summary beat many overlapping ones. For work that must survive a restart or a sleeping laptop, use a Fleet run instead.

Next