murmur spawn - Murmur

murmur spawn creates a new agent task, requests a VM from the pool, and starts a Claude Code (or Codex) session. This is the most important CLI command — it is how all work begins.

Synopsis

murmur spawn [flags] <slug> [description]

The slug is a short DNS-label-safe identifier (lowercase, alphanumeric, hyphens) that uniquely identifies the agent under your developer namespace. The description is the task prompt sent to Claude.

murmur spawn fix-auth-bug "Fix the authentication timeout in the session middleware"

What happens when you spawn

The CLI resolves your workspace, credentials, and configuration
An agent is created with the slug and description
A warm VM is claimed from the pool (instant if available) or a new one is booted
Your encrypted credentials are decrypted by the control plane and re-sealed for the VM
The repository is cloned and Claude Code (or Codex) starts with your task description
The agent works autonomously until completion or idle

Session modes

Mode	Flag	Description	Use case
Autonomous	(default)	Headless. Agent works until done, then idles or terminates.	Fire-and-forget tasks, PR creation
Interactive	`-i`	Claude runs in a tmux session with web terminal access	Debugging, exploration, pair programming
Streaming	`--stream`	Bidirectional session channel via the CLI	Dashboard live view, programmatic interaction

murmur spawn fix-bug "Fix the auth timeout"              # autonomous
murmur spawn -i explore "Explore the codebase"           # interactive
murmur spawn --stream live-task "Build the login page"   # streaming

Interactive mode

Interactive mode (-i) starts Claude in a tmux session and opens a web terminal. After spawning, connect with SSH:

murmur ssh --attach my-task       # attach to Claude's tmux session
murmur ssh my-task                # login shell on the VM

The web terminal URL is printed at spawn time and is also available in the dashboard.

Streaming mode

Streaming mode (--stream) keeps a bidirectional channel open between the CLI and the agent. Claude’s output streams to your terminal in real time, and you can send input interactively.

Flags reference

Core flags

Flag	Short	Type	Description
`--purpose`		string	Human-readable summary of the agent’s goal (max 240 chars). Shown in the dashboard.
`--agent`		string	Agent persona name (e.g., `programmer`, `architect`). Loads persona configuration from the catalog.
`--model`		string	Model override (e.g., `claude-opus-4-6`, `claude-sonnet-4-6`, `gpt-5-4`).
`--backend`		string	Session backend: `claude` (default) or `codex`. Auto-detected from model if not set.
`--out`		string	Expected output artifact. Short keywords are expanded (see below).
`--append-system-prompt`		string	Additional instructions appended to the agent’s system prompt.
`--workspace`	`-w`	string	Override workspace from config.

Session mode flags

Flag	Short	Type	Description
`-i`		bool	Interactive mode — starts a tmux session with web terminal.
`--stream`		bool	Streaming mode — bidirectional session channel in the terminal.

Lifecycle flags

Flag	Type	Description
`--on-idle`	string	Behavior when the agent finishes its turn. See idle behavior below.
`--pilot`	string	Completion check strategy: `none` (default) or `assessor` (runs up to 3x).
`--wait`	bool	Block until the agent reaches a terminal phase before returning.
`--dequeue-strategy`	string	How queued follow-ups are delivered: `all` (default), `one`, `five`.

Repository and environment flags

Flag	Type	Description
`--repo`	string	Repository override. Repeatable. Format: `URL`, `URL=base`, or `URL=base:working`.
`--task`	string	Pre-populate the agent’s task checklist. Repeatable.
`--input`	string	Key=value input for flights. Repeatable.
`-e`	string	Forward a local environment variable to the agent VM. Repeatable.

Resurrection and forking flags

Flag	Type	Description
`--resurrect`	bool	Resume a completed/killed agent on the same branch with full conversation history.
`--force-new`	bool	Start fresh even if a prior session exists for this slug.
`--fork-from`	string	Branch off another agent’s session into a new independent agent.

Flight flags

Flag	Type	Description
`--flight`	string	Path to a flight document relative to `.murmur/flights/`. Executes via a pilot agent.
`--input`	string	Context inputs for the flight (key=value). Repeatable.

Expected output (`--out`)

The --out flag tells the agent what artifact to produce. Short keywords are expanded:

Keyword	Expansion
`pr`	Open a pull request when done
`push`	Push changes to the branch (no PR)
`respond`	Respond with analysis only, no code changes
(freeform)	Passed through verbatim as instructions to the agent

murmur spawn refactor-api "Refactor the API layer" --out pr
murmur spawn analyze-perf "Profile the hot path" --out respond
murmur spawn custom-task "Build the feature" --out "Open a PR and post a summary comment"

Idle behavior (`--on-idle`)

Controls what happens when the agent finishes its current turn:

Value	Behavior
`sleep` (default)	Stop the VM, preserve agent state. Wake to resume later.
`terminate`	End the agent session immediately after the first idle.
`terminate-when-prs-resolved`	Stay alive until all opened PRs are merged or closed, then terminate.
`keep-alive`	Keep the VM running indefinitely, waiting for follow-ups.

murmur spawn one-shot "Quick fix" --on-idle terminate
murmur spawn pr-watcher "Fix and monitor" --on-idle terminate-when-prs-resolved
murmur spawn long-lived "Background worker" --on-idle keep-alive

Agent personas (`--agent`)

An agent persona is a reusable configuration stored in the catalog. It can define a system prompt, model preference, allowed/disallowed tools, max turns, and a default task checklist.

murmur spawn --agent architect design-review "Review the authentication architecture"
murmur spawn --agent programmer impl-feature "Implement the feature"

Model and backend selection

# Claude Code (default backend)
murmur spawn --model claude-opus-4-6 task1 "Complex reasoning task"
murmur spawn --model claude-sonnet-4-6 task2 "Straightforward implementation"

# Codex (auto-detected from model prefix)
murmur spawn --model gpt-5-4 task3 "Implement the feature with Codex"

# Explicit backend override
murmur spawn --backend codex --model gpt-5-4 task4 "Codex task"

Repository overrides (`--repo`)

Override the repos cloned on the VM. Each --repo flag adds or overrides a repository. The format supports branch overrides:

Format	Description
`URL`	Clone at the workspace-configured branch
`URL=base`	Override the base branch
`URL=base:working`	Override both the base and working branch

# Clone an additional repo
murmur spawn multi-repo "Cross-repo refactor" \
  --repo https://github.com/acme/api \
  --repo https://github.com/acme/sdk

# Override branch
murmur spawn feature-work "Build on feature branch" \
  --repo https://github.com/acme/api=feature/new-auth

# Override base and working branch
murmur spawn hotfix "Cherry-pick fix" \
  --repo https://github.com/acme/api=main:hotfix/fix-123

Flights (`--flight`)

Run a flight document through a pilot agent. The path is relative to .murmur/flights/:

murmur spawn --flight refactor.md my-refactor

With input context variables:

murmur spawn --flight triage.md --input repo=acme-corp/api --input number=42 bug-42

The pilot agent reads the flight Markdown, interprets the DAG of agents, and orchestrates execution. See Flights for the flight document format.

Fanout

Spawn one agent per line from a file. Each line replaces {} in the slug and description templates:

# Fanout from a file with murmur each (see Agent Management)
cat modules.txt | murmur each "fix-{}" "Fix the failing tests in {}"

# Or via the MCP spawn tool with the `each` parameter

Resurrection (`--resurrect`)

Resume a completed, failed, or killed agent. The agent gets the same branch, full conversation history, and a new VM:

murmur spawn --resurrect fix-auth-bug "Continue where you left off"

Resurrection loads the agent’s GCS session snapshot. The slug must match an existing prior agent. The agent resumes with its full conversation context intact.

Forking (`--fork-from`)

Branch off another agent’s session into a new independent agent. The fork gets the parent’s conversation history but diverges from that point:

murmur spawn --fork-from fix-auth-bug experiment "Try a different approach to the auth fix"

The original agent is unaffected. The forked agent gets a new slug, new branch, and new VM.

Pre-populating tasks (`--task`)

Set up the agent’s task checklist at spawn time:

murmur spawn impl-feature "Implement the new feature" \
  --task "Update the data model" \
  --task "Add API endpoints" \
  --task "Write integration tests" \
  --task "Update documentation" \
  --out pr

Environment variable forwarding (`-e`)

Forward local environment variables to the agent VM:

murmur spawn deploy-fix "Fix the deployment" \
  -e DEPLOY_ENV \
  -e FEATURE_FLAG_KEY

The variables must be set in your local shell. They are encrypted and delivered alongside your profile credentials.

System prompt customization

Append additional instructions to the agent’s system prompt:

murmur spawn careful-task "Refactor the auth module" \
  --append-system-prompt "Always run tests before committing. Never force-push."

Completion checks (`--pilot`)

The --pilot flag enables a completion assessor that evaluates whether the agent has actually finished its task:

Value	Behavior
`none` (default)	No completion check. Agent idles when Claude stops.
`assessor`	Run a completion assessor up to 3 times before allowing idle.

murmur spawn thorough-task "Implement and test the feature" --pilot assessor

Examples

Basic autonomous agent with PR output

murmur spawn fix-bug "Fix the null pointer in user.go line 42" --out pr

Interactive exploration session

murmur spawn -i explore "Explore the codebase and explain the architecture"

Flight execution with inputs

murmur spawn --flight deploy-pipeline.md \
  --input environment=staging \
  --input version=v2.1.0 \
  deploy-staging

Resurrect a previous agent

murmur spawn --resurrect fix-auth-bug "The tests are still failing -- fix the edge case"

Fork an agent to try a different approach

murmur spawn --fork-from fix-auth-bug alt-approach "Try using middleware instead"

Multi-repo agent with custom model

murmur spawn --model claude-opus-4-6 cross-repo-refactor \
  "Refactor the shared types across both repos" \
  --repo https://github.com/acme/api \
  --repo https://github.com/acme/sdk \
  --out pr

Long-lived agent that watches PRs

murmur spawn pr-shepherd "Fix and iterate on PRs until merged" \
  --on-idle terminate-when-prs-resolved \
  --out pr

Getting Started

Core Concepts

Guides

CLI Reference

MCP Server

Dashboard

Configuration

Security

Catalog Resources

API Reference

Troubleshooting

Documentation Index

​Synopsis

​What happens when you spawn

​Session modes

​Interactive mode

​Streaming mode

​Flags reference

​Core flags

​Session mode flags

​Lifecycle flags

​Repository and environment flags

​Resurrection and forking flags

​Flight flags

​Expected output (--out)

​Idle behavior (--on-idle)

​Agent personas (--agent)

​Model and backend selection

​Repository overrides (--repo)

​Flights (--flight)

​Fanout

​Resurrection (--resurrect)

​Forking (--fork-from)

​Pre-populating tasks (--task)

​Environment variable forwarding (-e)

​System prompt customization

​Completion checks (--pilot)

​Examples

​Basic autonomous agent with PR output

​Interactive exploration session

​Flight execution with inputs

​Resurrect a previous agent

​Fork an agent to try a different approach

​Multi-repo agent with custom model

​Long-lived agent that watches PRs

Synopsis

What happens when you spawn

Session modes

Interactive mode

Streaming mode

Flags reference

Core flags

Session mode flags

Lifecycle flags

Repository and environment flags

Resurrection and forking flags

Flight flags

Expected output (`--out`)

Idle behavior (`--on-idle`)

Agent personas (`--agent`)

Model and backend selection

Repository overrides (`--repo`)

Flights (`--flight`)

Fanout

Resurrection (`--resurrect`)

Forking (`--fork-from`)

Pre-populating tasks (`--task`)

Environment variable forwarding (`-e`)

System prompt customization

Completion checks (`--pilot`)

Examples

Basic autonomous agent with PR output

Interactive exploration session

Flight execution with inputs

Resurrect a previous agent

Fork an agent to try a different approach

Multi-repo agent with custom model

Long-lived agent that watches PRs