Skip to main content

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.

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]
On a VM, the slug is optional — omitting it queries the current agent’s own status.

​
Arguments

NameTypeRequiredDescription
slugstringon laptopThe agent’s slug. Optional on VMs (defaults to self).
--phasestringnoThe phase to wait for. Default: PHASE_RUNNING.
--workspacestringnoWorkspace name. Overrides the value from murmur.yaml.

​
Valid phases

PhaseMeaning
PHASE_STARTINGAgent is provisioning — acquiring a VM and preparing the workspace.
PHASE_RUNNINGAgent is actively working on a task.
PHASE_TASK_COMPLETEAgent finished a task and is waiting for follow-ups or will go idle.
PHASE_IDLEAgent is idle — VM is still running, waiting for a follow-up or sleep.
PHASE_SLEEPINGVM is stopped. The agent wakes on the next follow-up or murmur wake.
PHASE_CHECKS_PENDINGAgent is waiting for CI checks to complete on a PR.
PHASE_DESTROYINGAgent is shutting down and releasing its VM.
PHASE_COMPLETEDAgent finished and exited normally. Terminal.
PHASE_FAILEDAgent encountered an error. Terminal.
PHASE_CANCELEDAgent 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

murmur wait fix-auth

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
The command returns because PHASE_FAILED is terminal — it does not block forever waiting for PHASE_IDLE.

​
Errors

CodeMeaningWhat to do
NOT_FOUNDNo agent with that slug exists.Check the slug spelling. Use murmur ls to see running agents.
UNAUTHENTICATEDIdentity token is missing or expired.Run murmur auth or check your murmur.local.yaml configuration.
DEADLINE_EXCEEDEDThe 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.