# list\_worktrees

List every worktree with its repository, branch, agents and last measured size.

read-only · idempotent · MCP tool · [Worktree](https://komrad.dev/latest/api/worktree.md)

The call doesn't run git, so it is fast.

## Calling it

```bash
curl -X POST http://127.0.0.1:8787/komrad.worktree.v1.WorktreeService/ListWorktrees \
  -H 'Content-Type: application/json' \
  -d '{}'
```

```bash
komrad rpc list-worktrees
```

```json
{
  "name": "list_worktrees",
  "arguments": {}
}
```

Offered by the komrad MCP server to orchestrator agents.

## Request

### Empty

No fields.

## Response

### ListWorktreesResponse

| Field | Type | Description |
| --- | --- | --- |
| [`worktrees`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-ListWorktreesResponse-worktrees) | [Worktree\[\]](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-Worktree) | Every worktree in the worktree directories, in no set order. |
| [`dirs`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-ListWorktreesResponse-dirs) | string\[\] | The worktree directories read: the configured one and each workflow's own. |
| [`unreadable_dirs`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-ListWorktreesResponse-unreadable_dirs) | string\[\] | The worktree directories that could not be read. |

## Types

### Worktree

Worktree is one worktree directory on disk.

| Field | Type | Description |
| --- | --- | --- |
| [`dir`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-Worktree-dir) | string | The worktree's absolute path. |
| [`repo_dir`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-Worktree-repo_dir) | string | The repository the worktree was created from, read from the worktree's `.git` file, or where the repository used to be when git cannot read that file. |
| [`branch`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-Worktree-branch) | string | The branch checked out in the worktree. Empty when HEAD is detached or git cannot read the worktree. |
| [`readable`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-Worktree-readable) | bool | Whether the gitdir that the worktree's `.git` file names still exists. Git cannot read the worktree without it. |
| [`occupants`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-Worktree-occupants) | [WorktreeAgent\[\]](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-WorktreeAgent) | The agents working in the worktree, live ones first. |
| [`size_bytes`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-Worktree-size_bytes) | int64 | The disk space the worktree takes, in bytes, counting blocks and each hard-linked file once. Unset until measured and while the last measurement failed. |
| [`measured_at`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-Worktree-measured_at) | timestamp | When the worktree's size was last measured or last failed to be. Unset until first measured. |
| [`size_error`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-Worktree-size_error) | string | Why the last measurement failed. Empty when it succeeded. |
| [`last_active_at`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-Worktree-last_active_at) | timestamp | When the worktree was last active. This is the newest change to its agents, else when git last wrote its `.git` file, else its modification time. |
| [`fate`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-Worktree-fate) | [WorktreeFate](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-WorktreeFate) | What removes the worktree. |
| [`share_bytes`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-Worktree-share_bytes) | int64 | The worktree's share of [`size_bytes`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-Worktree-size_bytes), with each hard-linked file split evenly across its links. Unset when [`size_bytes`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-Worktree-size_bytes) is unset. |
| [`task`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-Worktree-task) | [WorktreeTask](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-WorktreeTask) | The task the worktree belongs to. Unset when no task owns it. |

### WorktreeAgent

WorktreeAgent is an agent working in a worktree.

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-WorktreeAgent-id) | uuid\* | The agent's id. |
| [`name`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-WorktreeAgent-name) | string | The agent's name. |
| [`state`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-WorktreeAgent-state) | [AgentState](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-agent-v1-AgentState) | The agent's state. |
| [`archived_at`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-WorktreeAgent-archived_at) | timestamp | When the agent was archived. Unset while the agent is live. |

### WorktreeTask

WorktreeTask is the task a worktree belongs to.

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-WorktreeTask-id) | uuid\* | The task's id, which is also the worktree directory's name. |
| [`slug`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-WorktreeTask-slug) | string | The task's slug. |
| [`archived_at`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-WorktreeTask-archived_at) | timestamp | When the task was archived. Unset while the task is live. |
| [`adopted`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-WorktreeTask-adopted) | bool | Whether the branch existed before the task was put on it. Deleting the task never deletes such a branch. |

### WorktreeFate

WorktreeFate is what removes a worktree directory.

| Value | Description |
| --- | --- |
| [`unowned`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-WorktreeFate-unowned) | No task owns the directory. [`remove_unowned_worktrees`](https://komrad.dev/latest/api/worktree/remove-unowned-worktrees.md) removes it. |
| [`archived`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-WorktreeFate-archived) | The directory's task is archived. Deleting the task removes it. |
| [`live`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-WorktreeFate-live) | The directory's task is live. Nothing removes it. |
| [`deleting`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-worktree-v1-WorktreeFate-deleting) | The directory's task is being deleted, which removes the directory. |

### AgentState

AgentState is what komrad last read an agent to be doing, from the end of its pane.

| Value | Description |
| --- | --- |
| [`idle`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-agent-v1-AgentState-idle) | The CLI is at rest with nothing typed. |
| [`thinking`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-agent-v1-AgentState-thinking) | The CLI is working on a turn. |
| [`waiting`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-agent-v1-AgentState-waiting) | The CLI is waiting for the person to answer a selection. |
| [`setting_up`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-agent-v1-AgentState-setting_up) | The agent is launching and doesn't have a pane to read yet. |
| [`failed_to_create`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-agent-v1-AgentState-failed_to_create) | The launch failed. [`retry_agent`](https://komrad.dev/latest/api/agent/retry-agent.md) launches the agent again. |
| [`failed_to_cleanup`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-agent-v1-AgentState-failed_to_cleanup) | A delete failed to clean up after the agent. `failure_reason` says why. |
| [`uncertain`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-agent-v1-AgentState-uncertain) | The pane could be read, but its end showed no known state. |
| [`errored`](https://komrad.dev/latest/api/worktree/list-worktrees.md#komrad-agent-v1-AgentState-errored) | The CLI is at rest after an API error ended the last turn. `turn_error` names the error. |
