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.
An agent is an autonomous Claude Code (or Codex) session running on a cloud VM. Agents clone repos, execute tasks, open pull requests, and can spawn child agents recursively.
What is an agent?
Under the hood, an agent is a managed process backed by a cloud VM. The platform manages the agent’s full lifecycle — provisioning, credential delivery, task execution, follow-ups, sleep/wake, and termination. You interact with agents through the CLI, MCP tools, or dashboard; the orchestration machinery is invisible.
Session modes
| Mode | Flag | Description | Use case |
|---|
| Autonomous | (default) | Headless. Agent works until done, then idles. | Fire-and-forget tasks, PR creation |
| Streaming | --stream | Bidirectional session channel | Dashboard live view, programmatic interaction |
murmur spawn fix-bug "Fix the auth timeout" # autonomous
murmur spawn --stream live-task "Build the login page" # streaming
Agent lifecycle
| Phase | What’s happening |
|---|
| Provisioning | Warm VM claimed from pool, credentials delivered |
| Running | Claude Code is active, executing the task |
| Idle | Claude finished its turn; agent waits for follow-ups, events, or timeout |
| Sleeping | VM stopped, agent state preserved; wake to resume |
| Completed | Agent finished successfully |
| Failed | Agent encountered an unrecoverable error |
| Killed | Manually terminated via murmur kill |
--on-idle flag controls what happens when an agent finishes its turn:
| Value | Behavior |
|---|
sleep (default) | Stop VM, preserve state. Wake to resume. |
terminate | End the agent session immediately. |
terminate-when-prs-resolved | Stay alive until all PRs are merged or closed, then terminate. |
keep-alive | Keep VM running indefinitely. |
Slugs and identity
Every agent has a slug — a short identifier you choose at spawn time:
murmur spawn fix-auth-bug "Fix the authentication timeout"
# ^^^^^^^^^^^^ this is the slug
{developer}/{slug} — e.g., alice/fix-auth-bug.
Recursive spawning
Agents can spawn children, and children can spawn children. This is the foundation of multi-agent orchestration.
alice/orchestrator
├── alice/orchestrator/backend-fix
├── alice/orchestrator/frontend-fix
│ └── alice/orchestrator/frontend-fix/test-runner
└── alice/orchestrator/docs-update
{ "tool": "spawn", "slug": "backend-fix", "description": "Fix the API endpoint" }
child_lifecycle event when children complete or fail.
Follow-ups and queue
You can send messages to running agents. Messages are queued and delivered when the agent is ready (between turns).
murmur queue add fix-auth-bug "Also fix the session expiry logic"
| Strategy | Behavior |
|---|
all (default) | Drain all queued follow-ups at once |
one | Deliver one message per turn |
five | Deliver up to five messages per turn |
Session resurrection and forking
Resurrect resumes a prior session from a GCS snapshot — same slug, same branch, full conversation history:
murmur spawn --resurrect fix-auth-bug "Continue where you left off"
murmur spawn --fork-from fix-auth-bug experiment "Try a different approach"
Agent personas
An agent persona is a reusable configuration stored in the catalog (agent-persona kind). 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"
Backend selection
Agents can run Claude Code or Codex:
murmur spawn --model claude-opus-4-6 task1 "..." # Claude Code (default)
murmur spawn --model gpt-5-4 task2 "..." # Codex (auto-detected from model)
murmur spawn --backend codex task3 "..." # Explicit backend
--reasoning-effort flag controls thinking depth: low, medium, high, xhigh, max (Claude) or low–xhigh (Codex).
