<!-- Markdown mirror. Canonical: https://empryo.com/docs/agents/dispatch -->

# Parallel subagents

> Split one task across subagents that run side by side, each on the model its job needs. Follow them live, steer them, or connect them in a workflow.

Empryo splits a task across subagents that work at the same time and report back. You don't have to ask: describe the result you want and Empryo decides when parallel work pays off, for example a refactor across several files, a question that spans modules, or carrying out a plan. For a one-file question it does the work itself. You can also ask directly: "check these five things in parallel".

[Watch five subagents run in the terminal lesson](/docs/terminal-guide#run-subagents-in-parallel).

## What you see

The dispatch panel lists every subagent with its task, its model, its live step, its tokens and its cost. Each one ends with Done or a reason it failed, and its report folds back into the conversation. On desktop the Subagents panel shows the same list, and every subagent opens to its full activity.

## How many at once

- A dispatch runs up to 8 tasks as written by default. Past that, research tasks are merged into fewer subagents. `taskRouter.maxDispatchTasks` raises the limit, to 24 at most.
- Up to 16 subagents run at the same time by default. `/router` sets the concurrency to 2, 4, 8, 12, 16, 24, 32 or Unlimited.
- Background subagents (`bg-1`, `bg-2`, and so on) keep working while you carry on the conversation. Their reports arrive on their own when they finish. By default the agent is woken once, when every subagent of a dispatch is done, with all the reports together. Set `agentFeatures.backgroundWake` to `each` to hear from each one as it finishes (also in `/agent-features` and the routing panel on desktop). A single dispatch can ask for `each` or `none` itself. In a [headless](/docs/surfaces/headless) run the prompt stays open until its background subagents report.
- [Workflows](/docs/agents/workflows) go further: parallel branches, review loops and graphs inside graphs.

Unlimited removes Empryo's own cap. With it off, Empryo has run 10,000 subagents in parallel. Provider rate limits, memory and your budget still apply.

## Each on its own model

The [task router](/docs/recipes/task-router) gives explorers, coders, cleanup and code review their own default model. A single task can name its model too, and a [custom agent](/docs/tools/agents) brings its own model, instructions, skills and tool rules. In the lesson recording, three subagents run on Claude Haiku 4.5, one on Claude Opus 5 and one on GPT-6 Astra.

## When helpers hit rate limits

If main chat works but helpers get throttled, your provider may treat non-streaming requests differently. Enable **Stream helper requests** for that provider in `/provider-settings` → **General**, or **Settings → Provider Options → Shared** on desktop. Helpers consume streams internally and return completed reports as usual. The opt-in is global, per provider, and off by default.

See [helper streaming compatibility](/docs/context/provider-options#stream-helper-requests) for setup, environment overrides and limits.

## What subagents share

- **File reads.** When one subagent has read a file, the others get it from memory instead of disk. Each still pays tokens to read it into its own context.
- **Safe writes.** When two subagents write the same file, the writes queue instead of racing.
- **Findings.** What one subagent discovers reaches the others at their next step.

## Where the savings come from

Subagents don't share one context, so the savings come from elsewhere:

- **The right model for each job.** Research can use a fast model while implementation and review use a stronger one. Compare real costs in `/usage`: a cheaper token rate does not always mean a cheaper task.
- **Symbols instead of whole files.** Subagents look up symbols through the Genome and the language server and read only the lines they need. See [code intelligence](/docs/concepts/intelligence).
- **Time.** Five subagents working at once finish sooner than one agent doing five jobs in a row.

## Steer them while they run

Type while subagents are working. Your message reaches them at their next step. See [steering](/docs/agents/steering).

To redirect a single subagent on desktop, open its activity view and type in its instruction box. The note reaches it at its next step and shows in its log with an "instructed" badge. Empryo can do the same on your behalf.

## Keep a subagent in the conversation

Normally a subagent answers once and exits. Empryo can instead start a **resident** subagent that stays available after each reply, so you can go back and forth like a thread with a colleague. Ask for it, for example "spawn an advisor and discuss". Residents show as `waiting` in the Subagents panel between replies.

A resident reuses files the main agent has already read, so a long conversation doesn't pay for them again. Its transcript has a size limit, and the oldest exchanges are dropped first.

Limits: up to 4 residents at a time, 12 exchanges each, and a resident left idle for 30 minutes is closed.

## Use your own agents

When you define your own agents as markdown files, Empryo sees their descriptions and can hand a task to one of them. The task then runs with that agent's instructions, model and tool rules, in the current turn or in the background. Subagents running under your definition show its name in the Subagents panel. See [agents](/docs/tools/agents).
