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

> List agents in the current workspace with their slug, lifecycle phase, VM, task progress, and accumulated cost — the default fleet overview.

Lists [agents](/concepts/agents) in the current workspace. By default, shows only your own active (non-terminal) agents. Use flags to include completed agents, other developers' agents, or to get machine-readable output.

On a VM, `murmur ls` lists child agents of the current agent.

## Synopsis

```bash theme={null}
murmur ls [flags]
```

## Arguments

| Name         | Type   | Required | Description                                                                                                                                                                                                 |
| ------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-a`         | bool   | no       | Also include terminal (completed, failed, canceled) [agents](/concepts/agents). Widens the phase filter only — it does not change which developers are listed (use `-A` or `-developer`). Default: `false`. |
| `-q`         | bool   | no       | Print only slugs, one per line. Default: `false`.                                                                                                                                                           |
| `-json`      | bool   | no       | Output as a JSON array. Default: `false`.                                                                                                                                                                   |
| `-A`         | bool   | no       | List all developers' [agents](/concepts/agents), not just your own. Default: `false`.                                                                                                                       |
| `-developer` | string | no       | List a specific developer's [agents](/concepts/agents) by username.                                                                                                                                         |
| `-workspace` | string | no       | Workspace name. Overrides the value from `murmur.yaml`.                                                                                                                                                     |

## Output

The default output is a tab-aligned table with five columns:

| Column     | Description                                                                                                                                                 |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SLUG`     | The [agent's](/concepts/agents) slug. For child agents, displayed as `parent/child`.                                                                        |
| `PHASE`    | Current lifecycle phase — `starting`, `running`, `task-complete`, `idle`, `sleeping`, `checks-pending`, `destroying`, `completed`, `failed`, or `canceled`. |
| `VM`       | VM instance name. Empty if no VM is assigned.                                                                                                               |
| `PROGRESS` | Latest progress event, formatted as `[label] detail (time ago)`. Labels include `text`, `tool`, `pr`, `commit`, and `push`.                                 |
| `COST`     | Cumulative API cost in USD (e.g. `$1.23`). Empty if zero.                                                                                                   |

When no [agents](/concepts/agents) match, the command produces no output and exits successfully.

### Quiet mode (`-q`)

Prints one slug per line with no header. Useful for scripting — pipe to `xargs` or loop over the result.

### JSON mode (`-json`)

Prints a JSON array of objects. Each object has `slug`, `phase`, `vm`, `progress`, `progress_at`, and `cost` fields. An empty result produces `[]`, not `null`.

## Examples

### List active agents

```bash theme={null}
murmur ls
```

```
SLUG          PHASE     VM                PROGRESS                                        COST
fix-auth      running   murmur-a1b2c3d4   [text] Investigating auth middleware (2m ago)    $0.42
add-tests     starting                                                                    
refactor-db   idle      murmur-e5f6g7h8   [pr] https://github.com/acme/api/pull/87 (1h ago)  $1.05
```

### Include completed agents

```bash theme={null}
murmur ls -a
```

```
SLUG          PHASE       VM                PROGRESS                                          COST
fix-auth      running     murmur-a1b2c3d4   [text] Investigating auth middleware (2m ago)      $0.42
add-tests     starting                                                                        
refactor-db   completed                     [pr] https://github.com/acme/api/pull/87 (3h ago)  $1.05
old-cleanup   canceled                                                                        $0.10
```

### List all developers' agents

```bash theme={null}
murmur ls -A
```

```
SLUG              PHASE     VM                PROGRESS                                    COST
fix-auth          running   murmur-a1b2c3d4   [text] Investigating auth middleware (2m ago)  $0.42
alice/add-tests   running   murmur-f9g0h1i2   [tool] Bash, Read (30s ago)                 $0.88
```

### List a specific developer's agents

```bash theme={null}
murmur ls -developer alice
```

### Slugs only for scripting

```bash theme={null}
murmur ls -q
```

```
fix-auth
add-tests
refactor-db
```

Use this to kill all active [agents](/concepts/agents):

```bash theme={null}
murmur ls -q | xargs -I{} murmur kill {}
```

### JSON output

```bash theme={null}
murmur ls -json
```

```json theme={null}
[
  {
    "slug": "fix-auth",
    "phase": "running",
    "vm": "murmur-a1b2c3d4",
    "progress": {
      "assistant_text": {
        "message": "Investigating auth middleware"
      }
    },
    "progress_at": "2026-05-14T10:30:00Z",
    "cost": 0.42
  }
]
```

### Child agents on a VM

When running on an [agent](/concepts/agents) VM, `murmur ls` lists child agents spawned by the current agent:

```bash theme={null}
murmur ls
```

```
SLUG        PHASE       VM                PROGRESS                          COST
fix-auth    running     murmur-a1b2c3d4   [tool] Bash, Edit (15s ago)      $0.30
add-tests   completed                     [push] main (5m ago)             $0.65
```

## Errors

| Code               | Meaning                                             | What to do                                                         |
| ------------------ | --------------------------------------------------- | ------------------------------------------------------------------ |
| `UNAUTHENTICATED`  | Identity token is missing or expired.               | Run `murmur auth` or check your `murmur.local.yaml` configuration. |
| `INVALID_ARGUMENT` | The `-developer` value contains invalid characters. | Use a plain username string without quotes or backslashes.         |

## Related

* [Agents](/concepts/agents) — concept overview
* [`murmur status`](/cli/status) — detailed status for a single agent
* [`murmur kill`](/cli/kill) — cancel an agent
* [`murmur spawn`](/cli/spawn) — start an agent