> ## 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.

# murmur wait

> Block until an agent reaches a target lifecycle phase — useful in scripts that need to wait for a spawn, completion, or termination event.

Blocks until an [agent](/concepts/agents) reaches a target [phase](/cli/status#phases), 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

```bash theme={null}
murmur wait [flags] [slug]
```

On a VM, the slug is optional — omitting it queries the current agent's own status.

## 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](/cli/sleep). |
| `PHASE_SLEEPING`       | VM is stopped. The agent wakes on the next follow-up or [`murmur wake`](/cli/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.                                                          |

<Note>
  If the agent reaches a terminal phase before the target phase, the command returns immediately with the terminal status.
</Note>

## Output

When the target phase is reached, the command prints the same status output as [`murmur status`](/cli/status) — workflow ID, phase, VM assignment, progress, output, and cost.

## Examples

### Wait for an agent to start running

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

| Code                | Meaning                                | What to do                                                                              |
| ------------------- | -------------------------------------- | --------------------------------------------------------------------------------------- |
| `NOT_FOUND`         | No agent with that slug exists.        | Check the slug spelling. Use [`murmur ls`](/cli/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`](/cli/status).    |
| —                   | `unknown phase "<value>"`              | The `--phase` value is not a recognized phase name. Use one of the phases listed above. |

## Related

* [Agents](/concepts/agents) — concept overview
* [`murmur status`](/cli/status) — check an agent's current status
* [`murmur sleep`](/cli/sleep) — stop an agent's VM
* [`murmur wake`](/cli/wake) — restart a sleeping agent's VM
* [`murmur spawn`](/cli/spawn) — start an agent
* [`murmur ls`](/cli/ls) — list running agents