Blocks until an agent reaches a target phase, then prints the agent’s status. Useful in scripts and CI pipelines that need to act on agent completion.
When called with --phase, the command returns as soon as the agent enters that phase — or enters a terminal phase (PHASE_COMPLETED, PHASE_FAILED, PHASE_CANCELED), whichever comes first. When called without --phase, the default target is PHASE_RUNNING.
The command is interruptible — press Ctrl-C to stop waiting.
Synopsis
murmur wait [flags] [slug]
Arguments
| Name | Type | Required | Description |
|---|
slug | string | on laptop | The agent’s slug. Optional on VMs (defaults to self). |
--phase | string | no | The phase to wait for. Default: PHASE_RUNNING. |
--workspace | string | no | Workspace name. Overrides the value from murmur.yaml. |
Valid phases
| Phase | Meaning |
|---|
PHASE_STARTING | Agent is provisioning — acquiring a VM and preparing the workspace. |
PHASE_RUNNING | Agent is actively working on a task. |
PHASE_TASK_COMPLETE | Agent finished a task and is waiting for follow-ups or will go idle. |
PHASE_IDLE | Agent is idle — VM is still running, waiting for a follow-up or sleep. |
PHASE_SLEEPING | VM is stopped. The agent wakes on the next follow-up or murmur wake. |
PHASE_CHECKS_PENDING | Agent is waiting for CI checks to complete on a PR. |
PHASE_DESTROYING | Agent is shutting down and releasing its VM. |
PHASE_COMPLETED | Agent finished and exited normally. Terminal. |
PHASE_FAILED | Agent encountered an error. Terminal. |
PHASE_CANCELED | Agent was killed. Terminal. |
If the agent reaches a terminal phase before the target phase, the command returns immediately with the terminal status.
Output
When the target phase is reached, the command prints the same status output as murmur status — workflow ID, phase, VM assignment, progress, output, and cost.
Examples
Wait for an agent to start running
workflow: github_oauth/alice/w/backend/fix-auth
phase: PHASE_RUNNING
vm: murmur-a1b2c3d4 (acme-agents/us-central1-a) [running]
version: 0.4+a1b2c3d4
Wait for task completion
murmur wait --phase PHASE_TASK_COMPLETE fix-auth
workflow: github_oauth/alice/w/backend/fix-auth
phase: PHASE_TASK_COMPLETE
response: Fixed the auth middleware to validate JWT expiry before checking claims.
pr: Fix JWT expiry validation (https://github.com/acme/backend/pull/42)
commits: 3
cost: $0.85
Wait in a script
murmur spawn fix-auth --task "Fix the JWT expiry bug"
murmur wait --phase PHASE_COMPLETED fix-auth
echo "Agent finished"
Agent fails before reaching target phase
murmur wait --phase PHASE_IDLE fix-auth
workflow: github_oauth/alice/w/backend/fix-auth
phase: PHASE_FAILED
PHASE_FAILED is terminal — it does not block forever waiting for PHASE_IDLE.
Errors
| Code | Meaning | What to do |
|---|
NOT_FOUND | No agent with that slug exists. | Check the slug spelling. Use murmur ls to see running agents. |
UNAUTHENTICATED | Identity token is missing or expired. | Run murmur auth or check your murmur.local.yaml configuration. |
DEADLINE_EXCEEDED | The wait was interrupted or timed out. | Re-run the command, or check the agent’s status with murmur status. |
| — | unknown phase "<value>" | The --phase value is not a recognized phase name. Use one of the phases listed above. |
