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.
Creates a new agent. Configures the agent’s repo(s), branch, model, session mode, idle behavior, and task checklist, then launches it on an ephemeral VM. If the agent is already running, returns an error — use queue_add to send a follow-up instead.
Equivalent to murmur spawn in the CLI.
Parameters
| Name | Type | Required | Description |
|---|
slug | string | yes | Agent task slug (e.g. fix-auth-bug). When flight is set, defaults to flight-<name>. |
description | string | yes (autonomous) | Task description or follow-up message. Required for autonomous mode unless flight is set. |
workspace | string | yes (new spawns) | Workspace name. The server resolves repos and environment from the workspace definition. |
branch | string | no | Working branch for every repo in this spawn. Per-repo overrides in repos[].branch take precedence. |
purpose | string | no | One-sentence human-readable summary of the agent’s goal (e.g. “Add pagination to the users API”). Displayed in the dashboard. Max 240 characters. |
model | string | no | Model override (e.g. claude-opus-4-6). |
agent | string | no | Claude Code agent persona (e.g. programmer, architect). |
backend | string | no | Code agent backend: claude (default) or codex. |
reasoning_effort | string | no | Reasoning effort level. Claude: low, medium, high, xhigh, max. Codex: low, medium, high, xhigh. Empty = model default. |
reasoning_summary | string | no | Codex reasoning summary: auto, concise, detailed, none. Only valid for backend=codex. |
verbosity | string | no | Codex verbosity: low, medium, high. Only valid for backend=codex. |
service_tier | string | no | Codex service tier: standard (default), fast, flex. Only valid for backend=codex. |
repos | object[] | no | Repos to clone with optional branch overrides. Each entry must have clone_url. See Repo object. |
session_mode | string | no | autonomous (default), interactive, or streaming. |
completion_check | string | no | none (default) or assessor (run completion assessor up to 3x before idling). |
on_idle | string | no | Idle behavior: sleep (default), terminate, terminate_when_prs_resolved, or keep_alive. |
dequeue_strategy | string | no | Follow-up dequeue strategy: all (default, drain all queued follow-ups), one (one per turn), or five (up to five per turn). |
resurrect | boolean | no | Resume a completed/killed agent on the same branch with its full conversation history. Requires the same slug. Default: false. |
force_new | boolean | no | Start fresh even if a prior session exists. Default: false. |
fork_from | string | no | Branch off another agent’s conversation into a new independent agent. Use a new slug — the fork gets the parent’s history but diverges from that point. |
tasks | string[] | no | Checklist items the agent must complete. |
append_system_prompt | string | no | Text appended to the agent’s system prompt. |
out | string | no | Expected output artifact. Short keywords are expanded: pr (open a pull request), push (push changes, no PR), respond (just respond, no code changes). Freeform text is passed through verbatim. |
flight | string | no | Flight file path relative to .murmur/flights/ (e.g. deploy.md). When set, reads and executes the flight via a pilot agent. |
flight_inputs | object | no | Context inputs for the flight, injected into the pilot prompt (e.g. {"repo": "org/repo", "number": "42"}). Only used when flight is set. |
each | string | no | Fanout: path to a file containing one item per line. Spawns one agent per line. slug and description must contain {} which is replaced with each item. |
Repo object
| Field | Type | Required | Description |
|---|
clone_url | string | yes | Canonical clone URL (e.g. https://github.com/org/repo). |
base_branch | string | no | Base branch to branch from (e.g. main). Resolved from tenant config or workspace default if omitted. |
branch | string | no | Working branch for this repo. Overrides the top-level branch. |
Response
Returns the slug of the spawned agent.
| Field | Type | Description |
|---|
slug | string | The slug of the spawned agent. |
each is used, returns a list of spawned slugs instead:
| Field | Type | Description |
|---|
slugs | string[] | Slugs of all spawned agents. |
count | integer | Number of agents spawned. |
Examples
Basic autonomous agent
{
"slug": "fix-auth-bug",
"description": "Fix the authentication bypass in the login handler",
"workspace": "backend",
"out": "pr"
}
{
"slug": "fix-auth-bug"
}
With model and persona
{
"slug": "api-refactor",
"description": "Refactor the users API to support pagination",
"workspace": "backend",
"model": "claude-opus-4-6",
"agent": "architect",
"on_idle": "terminate",
"out": "pr"
}
Multi-repo spawn with branch overrides
{
"slug": "cross-repo-fix",
"description": "Update the shared proto and regenerate clients",
"workspace": "platform",
"branch": "proto-update",
"repos": [
{"clone_url": "https://github.com/org/protos", "branch": "update-user-proto"},
{"clone_url": "https://github.com/org/api-server"}
],
"out": "pr"
}
Resume a dead agent
{
"slug": "fix-auth-bug",
"resurrect": true,
"description": "Continue fixing the auth bug — tests are still failing",
"workspace": "backend"
}
Fork from another agent
{
"slug": "fix-auth-v2",
"fork_from": "fix-auth-bug",
"description": "Try a different approach to the auth fix",
"workspace": "backend",
"out": "pr"
}
Flight execution
{
"slug": "deploy-v2",
"flight": "deploy.md",
"flight_inputs": {"version": "2.1.0"},
"workspace": "platform"
}
Fanout
{
"slug": "lint-{}",
"description": "Run linter on {}",
"each": "/tmp/repos.txt",
"workspace": "platform",
"out": "pr"
}
{
"slugs": ["lint-api-server", "lint-web-client", "lint-shared"],
"count": 3
}
Errors
| Code | Meaning | What to do |
|---|
ALREADY_EXISTS | An agent with that slug is already running. | Use queue_add to send a follow-up, or pass force_new: true to start fresh. |
INVALID_ARGUMENT | Missing required field, invalid enum value, or resurrect and force_new both set. | Check the error message and fix the input. |
NOT_FOUND | Workspace, flight, or fork source not found. | Verify the workspace name, flight path, or fork_from slug. |
UNAUTHENTICATED | Identity token is missing or expired. | Check credentials. |
murmur spawn — equivalent CLI command- Agents — concept overview
status — check agent statels — list running agentskill — cancel an agentqueue_add — send follow-up to a running agentwait — block until an agent reaches a target phase
