> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Agent Orchestration

> Spawn child agents, fan tasks across many items, run multi-step Flights, react to GitHub events, and stream follow-ups — every coordination pattern.

Most [agent](/concepts/agents) tasks are a single agent doing a single job. Sometimes one agent isn't enough, either because the work is too big, the steps depend on each other, or you want hands-off automation. Murmur gives you five tools for that. Pick the one that matches the shape of your problem.

| Your situation                                   | Use                                                         | The "why"                                                                                                                                                                    |
| ------------------------------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| One agent realizes it needs help mid-run         | [Parent and child](#parent-and-child)                       | Spawning a child gives the sub-task a clean context window and (optionally) a different [persona](/concepts/agent-personas), while the parent stays focused on coordination. |
| Same task, lots of items (files, modules, repos) | [Fanout](#fan-out-across-many-items)                        | Run them all in parallel. No coordination overhead because each agent is independent.                                                                                        |
| Multi-step workflow with dependencies            | [Flight DAG](#run-a-multi-step-flight)                      | Outputs flow between steps. Some steps wait, some run in parallel. The DAG makes the dependencies explicit so the work is reproducible.                                      |
| Hands-off response to a GitHub event             | [Event-driven Flight](#trigger-a-flight-from-github-events) | An issue or PR triggers a Flight automatically. No humans in the triage loop.                                                                                                |
| Add more work to an agent that's already going   | [Follow-ups](#stream-follow-ups-into-a-running-agent)       | The agent keeps its full context, so a follow-up costs less and goes faster than a fresh spawn.                                                                              |

See [Flights](/concepts/flights) and [Events](/concepts/events) for the underlying model. Every pattern below shows the CLI form first, then a parallel MCP form where the same thing can be triggered from inside a running agent's coding session. If you'd rather coordinate all of this conversationally, a [director](/concepts/director) is the agent that runs the patterns below on your behalf.

## Parent and child

The simplest pattern. From inside a running agent's coding session, use the Murmur MCP tools to spawn a child, wait for it, and read its result:

```text theme={null}
spawn(slug="child-task", description="Fix the API endpoint", out="pr")
wait(slug="child-task")
status(slug="child-task")
```

See [`mcp__murmur__spawn`](/mcp-server/spawn), [`mcp__murmur__wait`](/mcp-server/wait), and [`mcp__murmur__status`](/mcp-server/status). The same thing from a separate terminal uses [`murmur spawn`](/cli/spawn) and [`murmur status`](/cli/status).

The parent gets a `child_lifecycle` event when the child finishes or fails. The child runs in its own VM with its own clean context, so a long, noisy investigation in the child doesn't pollute the parent's transcript. This is the right move when an agent realizes mid-stream that a sub-task is meaty enough to deserve its own focus, or when it'd benefit from a different persona (e.g. spawn a `tester` to write coverage while the parent keeps shipping the feature).

## Fan out across many items

When you have the same task to run across a list (modules, files, repos), spawn one agent per item with [`murmur each`](/cli/each):

```bash theme={null}
echo -e "auth\npayments\nnotifications" \
  | murmur each fix-{} "Fix tests in the {} module" --workspace my-team
```

Each line becomes its own agent. `{}` is replaced with the item from that line. From the MCP side, [`mcp__murmur__spawn`](/mcp-server/spawn) accepts an `each` parameter:

```json theme={null}
{
  "tool": "spawn",
  "slug": "fix-{}",
  "description": "Fix tests in the {} module",
  "each": "/tmp/modules.txt"
}
```

Use this when the work is embarrassingly parallel and the agents don't need to coordinate. If they need to talk to each other or share work, you want a Flight DAG instead.

## Run a multi-step Flight

A **Flight** is a Markdown file that defines a DAG of agent tasks. You write the steps as headings, declare what each step depends on, and Murmur figures out what can run in parallel and what has to wait.

```markdown theme={null}
# Feature Implementation

## design
> persona: architect
> out: respond
Analyze the requirements and design the solution.

## backend
> needs: design
> out: pr
> gate: ci
Implement the backend based on the design.

## frontend
> needs: design
> out: pr
> gate: ci
Implement the frontend based on the design.

## integration-test
> needs: backend, frontend
> out: pr
Write integration tests that verify both work together.
```

Run it:

```bash theme={null}
murmur spawn --flight feature.md implement-feature --workspace my-team
```

A **pilot agent** runs the Flight. It spawns `design` first, then kicks off `backend` and `frontend` in parallel (both depend only on `design`), and finally `integration-test` once both upstream PRs merge. The `gate: ci` directive tells the pilot to wait for CI green before considering a step done, so downstream work only starts on commits that actually pass tests.

For critical Flights (anything you'd hate to silently fail), add `--pilot` to enable the **completion assessor**. It runs an evaluation loop after the Flight finishes (up to 3 times) to check whether the goal was actually achieved, not just whether the steps ran. Useful for things like deploys, where "ran without errors" and "actually deployed correctly" aren't the same thing:

```bash theme={null}
murmur spawn --flight deploy.md --pilot deploy-v2 "Deploy version 2"
```

## Trigger a Flight from GitHub events

You can register a Flight to fire automatically on GitHub activity. Put an `on:` block at the top of the file:

```markdown theme={null}
---
workspace: my-team
on:
  issue_opened:
    repos: [https://github.com/my-org/my-repo]
    labels: [bug]
---

# Bug Fixer

## triage
> persona: architect
> out: respond
Analyze the bug report and propose a fix.

## fix
> continues: triage
> out: pr
> gate: ci
Implement the fix.
```

Store it in the catalog with `murmur set` (the CLI command, see [`murmur set`](/cli/set)):

```bash theme={null}
murmur set flight bug-fixer < bug-fixer.md
```

Now every new issue labeled `bug` automatically spawns this Flight. The agent triages, proposes, fixes, opens a PR, and gates on CI. Humans only get involved when there's something interesting to review.

This pattern shines when the trigger is external and frequent: bug reports, dependabot PRs, CI failures, security alerts. Anything that arrives on a schedule you don't control.

## Stream follow-ups into a running agent

Sometimes you want to add more work to an agent that's already going, instead of starting a new one:

Start the agent with [`murmur spawn`](/cli/spawn) and `--on-idle keep-alive`, then push follow-ups in with [`murmur queue add`](/cli/queue-add):

```bash theme={null}
murmur spawn --on-idle keep-alive long-task "Build the dashboard"

# While it's working, or even after it goes idle:
murmur queue add long-task "Also add dark mode support"
murmur queue add long-task "Fix the responsive layout on mobile"
```

From an agent's own coding session, the equivalent MCP tool is [`mcp__murmur__queue_add`](/mcp-server/queue-add).

The agent keeps its full context (everything it already knows about your codebase, the conventions you use, the bugs it's already worked around), so a follow-up costs less and lands faster than respawning. The `--on-idle keep-alive` flag tells the VM not to shut down when the agent thinks it's done, so the queue keeps a path forward.

Set the delivery cadence at spawn time with `--dequeue-strategy`:

```bash theme={null}
murmur spawn --on-idle keep-alive --dequeue-strategy one long-task "Build the dashboard"
```

`one` delivers one queued message per turn (good when you want the agent to finish each follow-up before seeing the next). `all` delivers the whole queue at once. Default is `auto`, which delivers up to five follow-ups of one kind per turn and never mixes manual follow-ups with auto-generated events (PR comments, CI results, conflict resolutions) — your message always gets the agent's undivided attention.

## Watch what's happening

For any of the patterns above, you can see the whole agent tree at once with [`murmur status`](/cli/status):

```bash theme={null}
murmur status <root-slug> --children --timeline
```

Or open the dashboard's agent tree view for a live picture of every agent, its status, its cost, and the events flowing between them.