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

# status

> MCP tool that queries an agent's current state — lifecycle phase, task progress, PR artifacts, cost, child agents, and recent timeline events.

Queries an [agent's](/concepts/agents) current state. Returns the phase, VM assignment, progress, output (PRs, commits, cost), and optionally child statuses and lifecycle timeline.

Equivalent to [`murmur status`](/cli/status) in the CLI.

## Parameters

| Name        | Type      | Required | Description                                                                                                                         |
| ----------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `slug`      | string    | yes      | Agent task slug (e.g. `fix-bug`). Use an absolute path like `/w/workspace/u/account/slug` to target an agent outside your own path. |
| `children`  | boolean   | no       | Include child agent statuses in the response. Default: `false`.                                                                     |
| `timeline`  | string\[] | no       | Timeline event types to include. Omit to exclude timeline.                                                                          |
| `workspace` | string    | no       | Workspace name. Overrides the session default.                                                                                      |

### Timeline event types

| Type           | What it captures                                               |
| -------------- | -------------------------------------------------------------- |
| `phase`        | Phase transitions (starting → running → task-complete → idle). |
| `child`        | Child agent lifecycle changes.                                 |
| `taskComplete` | Agent finished a task turn.                                    |
| `commit`       | Agent made a git commit.                                       |
| `push`         | Agent pushed to remote.                                        |
| `checks`       | CI check status updates.                                       |
| `followUp`     | Follow-up messages delivered to the agent.                     |
| `upload`       | File uploads.                                                  |

## Response

Returns the agent's full status as a JSON object. Fields are present only when they have a value.

| Field                | Type      | Description                                                                  |
| -------------------- | --------- | ---------------------------------------------------------------------------- |
| `agentId`            | object    | The agent's identity — tenant, account, workspace, slug path.                |
| `phase`              | string    | Current lifecycle phase (e.g. `PHASE_RUNNING`, `PHASE_TASK_COMPLETE`).       |
| `vm`                 | object    | VM instance name, project, zone.                                             |
| `vmStopped`          | boolean   | `true` when the VM is stopped (sleeping).                                    |
| `version`            | string    | The murmur version running on the VM.                                        |
| `progress`           | object    | Latest progress update — label, detail, timestamp.                           |
| `sessionMode`        | string    | `SESSION_MODE_INTERACTIVE` for interactive sessions.                         |
| `currentDescription` | string    | The agent's current task description.                                        |
| `queuedFollowUps`    | string\[] | Pending follow-up messages.                                                  |
| `output`             | object    | Agent output — `response` text, `prs` array, `commits` count, `cost` in USD. |
| `children`           | object\[] | Child agent statuses (only when `children: true`).                           |
| `timeline`           | object\[] | Lifecycle events (only when `timeline` is set).                              |

## Examples

### Basic status check

```json theme={null}
{
  "slug": "fix-auth"
}
```

Response:

```json theme={null}
{
  "agentId": {
    "tenant": {"provider": "PROVIDER_GITHUB_OAUTH", "org": "alice"},
    "ownerProvider": "PROVIDER_GITHUB_OAUTH",
    "account": "alice",
    "workspace": "backend",
    "agent": ["fix-auth"]
  },
  "phase": "PHASE_RUNNING",
  "vm": {"instanceName": "murmur-a1b2c3d4", "project": "acme-agents", "zone": "us-central1-a"},
  "version": "0.4+a1b2c3d4",
  "progress": {"label": "tool", "detail": "Running tests", "timestamp": "2026-05-14T10:30:00Z"},
  "output": {"cost": 0.42}
}
```

### With children

```json theme={null}
{
  "slug": "director",
  "children": true
}
```

### With timeline

```json theme={null}
{
  "slug": "fix-auth",
  "timeline": ["phase", "taskComplete", "commit"]
}
```

### Absolute slug targeting another agent

```json theme={null}
{
  "slug": "/w/backend/u/bob/api-refactor"
}
```

## Errors

| Code              | Meaning                               | What to do                                                        |
| ----------------- | ------------------------------------- | ----------------------------------------------------------------- |
| `NOT_FOUND`       | No agent with that slug exists.       | Check the slug. Use [`ls`](/mcp-server/ls) to see running agents. |
| `UNAUTHENTICATED` | Identity token is missing or expired. | Check the agent's credentials.                                    |

## Related

* [`murmur status`](/cli/status) — equivalent CLI command
* [Agents](/concepts/agents) — concept overview
* [`spawn`](/mcp-server/spawn) — create an agent
* [`ls`](/mcp-server/ls) — list running agents
* [`kill`](/mcp-server/kill) — cancel an agent
* [`wait`](/mcp-server/wait) — block until an agent reaches a target phase