Parallel runs
For a goal with several parts, forge splits it into tasks, gives each one a model that fits, runs them at the same time in separate worktrees, and reviews each one on its own diff.
Turning it on
Add --decompose-level. It sets how finely the goal is split:
| Level | Split |
|---|---|
low | only the obviously separate pieces: 2 to 3 tasks |
medium | one task per module or feature slice: usually 4 to 6 |
high | as fine as each task can still be reviewed on its own: usually 7 to 12 |
/forge "add auth: tokens, middleware, login, rate limit, docs" \ --decompose-level medium --profile balanced
When an agent drives the run through forge-parallel.sh auto, a small goal skips the planner and runs as one task, and a plan that could only run one task after another is merged into a single task, since waves of one buy nothing. --collapse-chains asks for that merge on any plan.
Routing each task to a model
forge rates every task low, medium or high by the judgment it needs, not its size: a 500-line rename is low, a 10-line concurrency fix is high. Tasks don't exist yet when you type the command, so you map models to difficulties up front:
# one dwarf for everything --dwarf sol:xhigh # one per difficulty; plain --dwarf covers any level you don't name --dwarf-high sol:xhigh --dwarf-low haiku:xhigh --dwarf sonnet:medium # share a level between models, taking turns: neither quota carries it alone --dwarf-medium sonnet:medium,gemini:high:antigravity,grok:high
Reviewers work the same way with --qa, --qa-high, --qa-medium and --qa-low. Sizing the reviewer to the task costs less for the same verdicts. Or skip all of it with --profile balanced.
Now and then forge tries the neighbouring level's model on a row you left to it, to learn which models do well on your code. Those rows are marked * in the table, before anything is spent. --explore 0 turns it off.
You approve the table
After planning, forge shows every task, its difficulty, the model that builds it and the one that reviews it, and its planned approach. Then it stops. Nothing has been dispatched.
This is the free moment: say "task 2 is really medium" and it re-routes by your rules, or name another model for one row. A big high split can be 20 dispatches or more, and this is where you see it. If a task ends up with no model, forge refuses to run rather than invent one. With history, forge also prints a forecast: likely tokens, time and first-try pass rate per task.
Commit first. Worktrees start from your last commit, so edits you haven't committed are invisible to every dwarf. forge warns loudly when it sees them. A parallel run also needs a git repository.
One plan for every seam
Two dwarves can each stay in their lane, pass their own review, and still invent interfaces that don't fit. So forge plans the approach for every task in one pass before dispatching. By default your agent does it; --planner <model> hands it to a model you name, once per run. The reviewer gets the plan as the intended shape, so it can say "this works, but it isn't what was agreed".
How tasks run
One dwarf per worktree
Every task gets its own git worktree and a fresh model session, so one confused task can't spill into another. Each dwarf also gets a short brief: the goal, its own task, the files it owns, and which tasks have already merged into its starting point.
Waves follow the files
Tasks run together only when what they depend on has merged and they own different files. Two dwarves editing one file would make a conflict no reviewer could untangle, so forge holds one back and says why. A scheduler starts each task the moment it can, up to --max-parallel (3 by default). If almost every task waits on another, the goal needs a different split, not more parallelism.
Plan, run, integrate
Through /forge your agent drives these steps. They're also plain commands:
PLAN=/tmp/forge-auth # 1. plan and read the routing bash scripts/forge-parallel.sh plan "$PLAN" --repo ~/dev/api --profile balanced # 2. see exactly what would be dispatched bash scripts/forge-parallel.sh run "$PLAN" --dry-run # 3. run it, four at a time, retrying rejected tasks up to twice bash scripts/forge-parallel.sh run "$PLAN" --max-parallel 4 --retry-failed 2 # 4. bring the passing work into your branch bash scripts/forge-parallel.sh integrate "$PLAN" --approved
forge-parallel.sh auto goes from a goal file to the approval table in one blocking command, so even a small model can orchestrate. Until step 4, all work lives on branches forge made for itself.
Tasks that are a command
A codemod or a generated file doesn't need a model to type it. Put script in a row's dwarf column and write the command as an executable tasks/<id>/run: forge runs it in the task's worktree, from the task's starting point on every attempt, under the plan's timeout. A command that fails isn't reviewed; one that succeeds is reviewed as a script's output, like any other task.
A plan that starts where another ended
A second milestone can build on the first before either reaches your branch. plan <dir> --after <earlier plan> starts from the earlier plan's integration branch, once all its tasks merged. If the earlier plan moves on, run stops and says so, and integrate names the whole chain it brings in.
Interrupted runs
Ctrl-C stops the running tasks, keeps their partial work, and prints how to retry each. Run the same run again and it picks up: merged tasks are skipped, saved passes merge, and tasks paused by a provider problem start again on their own. To pause on purpose, drain the run instead; see Steering a live run.
Full reference Every flag and edge case: docs/decomposed-runs.md