Multi-Agent Orchestration

Most agent 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	Spawning a child gives the sub-task a clean context window and (optionally) a different persona, while the parent stays focused on coordination.
Same task, lots of items (files, modules, repos)	Fanout	Run them all in parallel. No coordination overhead because each agent is independent.
Multi-step workflow with dependencies	Flight DAG	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	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	The agent keeps its full context, so a follow-up costs less and goes faster than a fresh spawn.

See Flights and 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 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:

spawn(slug="child-task", description="Fix the API endpoint", out="pr")
wait(slug="child-task")
status(slug="child-task")

See mcp__murmur__spawn, mcp__murmur__wait, and mcp__murmur__status. The same thing from a separate terminal uses murmur spawn and murmur 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:

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 accepts an each parameter:

{
  "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.

# 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:

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:

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:

---
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):

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 and --on-idle keep-alive, then push follow-ups in with murmur queue add:

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. 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:

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:

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.

Getting Started

Core Concepts

Guides

Multi-Agent Orchestration

Parent and child

Fan out across many items

Run a multi-step Flight

Trigger a Flight from GitHub events

Stream follow-ups into a running agent

Watch what’s happening

​Parent and child

​Fan out across many items

​Run a multi-step Flight

​Trigger a Flight from GitHub events

​Stream follow-ups into a running agent

​Watch what’s happening

Parent and child

Fan out across many items

Run a multi-step Flight

Trigger a Flight from GitHub events

Stream follow-ups into a running agent

Watch what’s happening