Run Claude Code sub-agents in parallel: a desk-and-builders workflow
Sub-agents are most useful when a job splits into pieces that do not depend on each other. The failure mode is not that they cannot work in parallel; it is that the main session turns into a worker, or the briefs are vague, or two builders overwrite one folder. This is the workflow we use, written so you can copy it.
The shape: a desk and builders
- The desk is the main session. It reads the state page, keeps the backlog stocked, writes briefs, reviews what comes back and ships. It does a task itself only when that is quicker than writing the brief.
- Builders are sub-agents. Each takes one backlog item, works in its own folder, and hands back a short report.
- The repo is the shared memory: a builder-rules file every builder reads first, a backlog, a state page and a log. Nothing important lives only in a conversation.
Step 1: write the rules once
Put everything that applies to every builder in ops/BUILDER-RULES.md: what they may not do (secrets, spending, sending messages to people), how to leave their changes (uncommitted, with a list of changed paths), where to write the report, and any domain limits. Once it exists, a brief can be three lines.
Step 2: write the brief
You are builder <ID> for <company>. Read ops/BUILDER-RULES.md and CLAUDE.md first. Do not spawn your own sub-agents.
Goal: <one sentence naming the buyer or the number this moves>. Scope: <folder(s)>. Leave changes uncommitted and list the paths.
Done when: <observable condition>. Report to ops/reports/<date>-<ID>.md with a gate (indicator by <date+7>, result by <date+30>).
For new or risky work use the long form: why this and why now (the evidence), goal, scope and what not to touch, inputs, constraints, three checks a stranger could repeat, and a gate with a kill threshold. Rules that make briefs work:
- Name the buyer or the metric. "Build a scraper" fails; "build what the twelve people asking in this forum would pay for" works.
- Paste numbers into the brief. Assume the sub-agent may have no shell. If it needs the output of a script, you run the script and paste it.
- One folder per builder. Parallelism is across folders; two builders in one folder overwrite each other.
- Say what done looks like from the outside. "Returns data from a clean machine" beats "works".
- Ask for follow-ups. Three next items per report is how the backlog refills without you.
- Pick the model tier on purpose. A mid-tier model for most building; the strongest only for legal calls and hard judgment; never the cheapest tier for work that must be right the first time.
Step 3: launch in one message
Independent briefs go out together, in the foreground, in a single message. Two things we learned the hard way: a headless session ends when the main agent answers, and background sub-agents die with it, so a scheduled run should wait for its builders. And some sub-agents are refused tools the desk has, so never make a brief depend on a shell: the desk runs the script and pastes the result.
Step 4: take the handback
# Report <ID>
## Shipped (paths, URLs, numbers)
## Gate (leading indicator, date to read it, kill threshold)
## Failed or refused
## Follow-ups (3 lines, each with the evidence that produced it)
The desk reads the report, checks the "done when" from outside, adds the three follow-ups to the backlog, writes one line in the log and starts the next item in the same turn. Keep a target number of builders in flight; fewer than the target is a bug to fix in that turn, not a quiet moment.
Guard rails that earn their place
- A gate before every bet: indicator, read date, kill threshold. A gate re-dated twice is killed.
- A check that has never failed proves nothing. Every new gate ships with a known-bad case it must reject.
- Verify from where the user stands. A pass on your own machine can hide a failure that only shows from outside.
- One message per contact. If agents can send mail, make the tool refuse a second send to someone who has not replied.
- Watch cost. Parallel builders multiply usage. Put the number in flight and the model tier in
CLAUDE.mdand change them on purpose.
Where the files come from
The constitution that ties this together is walked through in the CLAUDE.md template guide. The builder rules, brief, handback, backlog, state-page, log and strategy templates above are in the Agent-Run Company Kit (US$19), ready to copy and fill in.
More from this set
- A CLAUDE.md template for a company run by Claude Code (free walkthrough)
- Headless Claude Code on a timer: a minimal scheduled runner
- 14 lessons from running a company on AI agents (free excerpt)
- Agent-Run Company Kit for Claude Code (US$19)
Related guides
- A CLAUDE.md template for a company run by Claude Code (free walkthrough)
- Headless Claude Code on a timer: a minimal scheduled runner
- 14 lessons from running a company on AI agents (free excerpt)
- Agent-Run Company Kit for Claude Code (US$19)
- SPF, DKIM and DMARC checker: free, runs in your browser
- Email header analyzer: free, runs in your browser