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

# ls

> MCP tool that lists agents in the current workspace with their phase, task progress, VM, and cost — the fleet overview for coding agents.

Lists [agent](/concepts/agents) tasks. Returns the slug, phase, VM assignment, progress, and cost for each task. By default shows only active tasks for the calling developer.

Two independent scopes control the result: `developer` selects **which accounts** are listed, and `include_terminal` selects **which phases** are listed. `include_terminal` never widens the set of accounts — to see other developers' agents, set `developer`.

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

## Parameters

| Name               | Type    | Required | Description                                                                                                                                                                                                            |
| ------------------ | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `include_terminal` | boolean | no       | Also include agents in terminal states (completed, failed, canceled). Widens the phase filter only — it does **not** change which accounts are listed (use `developer` for that). Default: `false` (live agents only). |
| `developer`        | string  | no       | Which accounts to list — the only way to widen account scope. `""` (default) lists only the calling account's agents; `*` lists every account; `alice` lists one specific account.                                     |
| `workspace`        | string  | no       | Workspace name. Overrides the session default.                                                                                                                                                                         |

## Response

Returns a JSON array of agent summary objects.

| Field      | Type   | Description                                                            |
| ---------- | ------ | ---------------------------------------------------------------------- |
| `slug`     | string | Agent task slug.                                                       |
| `phase`    | string | Current lifecycle phase (e.g. `PHASE_RUNNING`, `PHASE_TASK_COMPLETE`). |
| `vm`       | object | VM instance name, project, zone.                                       |
| `progress` | object | Latest progress update — label, detail, timestamp.                     |
| `cost`     | number | Cumulative cost in USD.                                                |

## Examples

### List active agents

```json theme={null}
{}
```

Response:

```json theme={null}
[
  {
    "slug": "fix-auth",
    "phase": "PHASE_RUNNING",
    "vm": {"instanceName": "murmur-a1b2c3d4", "project": "acme-agents", "zone": "us-central1-a"},
    "progress": {"label": "tool", "detail": "Running tests", "timestamp": "2026-05-14T10:30:00Z"},
    "cost": 0.42
  }
]
```

### Include completed agents

```json theme={null}
{
  "include_terminal": true
}
```

### All developers in a workspace

```json theme={null}
{
  "developer": "*",
  "workspace": "backend"
}
```

## Errors

| Code              | Meaning                               | What to do         |
| ----------------- | ------------------------------------- | ------------------ |
| `UNAUTHENTICATED` | Identity token is missing or expired. | Check credentials. |

## Related

* [`murmur ls`](/cli/ls) — equivalent CLI command
* [`status`](/mcp-server/status) — detailed status for a single agent
* [`spawn`](/mcp-server/spawn) — create an agent
* [`kill`](/mcp-server/kill) — cancel an agent