list_worktrees
List every worktree with its repository, branch, agents and last measured size.
read-onlyidempotentMCP toolWorktree
The call doesn't run git, so it is fast.
Calling it#
curl -X POST http://127.0.0.1:8787/komrad.worktree.v1.WorktreeService/ListWorktrees \
-H 'Content-Type: application/json' \
-d '{}'komrad rpc list-worktrees{
"name": "list_worktrees",
"arguments": {}
}Offered by the komrad MCP server to orchestrator agents.
Request#
Empty#
No fields.
Response#
ListWorktreesResponse#
| Field | Type | Description |
|---|---|---|
worktrees | Worktree[] | Every worktree in the worktree directories, in no set order. |
dirs | string[] | The worktree directories read: the configured one and each workflow's own. |
unreadable_dirs | string[] | The worktree directories that could not be read. |
Types#
Worktree#
Worktree is one worktree directory on disk.
| Field | Type | Description |
|---|---|---|
dir | string | The worktree's absolute path. |
repo_dir | string | The repository the worktree was created from, read from the worktree's |
branch | string | The branch checked out in the worktree. Empty when HEAD is detached or git cannot read the worktree. |
readable | bool | Whether the gitdir that the worktree's |
occupants | WorktreeAgent[] | The agents working in the worktree, live ones first. |
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 | timestamp | When the worktree's size was last measured or last failed to be. Unset until first measured. |
size_error | string | Why the last measurement failed. Empty when it succeeded. |
last_active_at | timestamp | When the worktree was last active. This is the newest change to its agents, else when git last wrote its |
fate | WorktreeFate | What removes the worktree. |
share_bytes | int64 | The worktree's share of |
task | 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 | uuid* | The agent's id. |
name | string | The agent's name. |
state | AgentState | The agent's state. |
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 | uuid* | The task's id, which is also the worktree directory's name. |
slug | string | The task's slug. |
archived_at | timestamp | When the task was archived. Unset while the task is live. |
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 | No task owns the directory. |
archived | The directory's task is archived. Deleting the task removes it. |
live | The directory's task is live. Nothing removes it. |
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 | The CLI is at rest with nothing typed. |
thinking | The CLI is working on a turn. |
waiting | The CLI is waiting for the person to answer a selection. |
setting_up | The agent is launching and doesn't have a pane to read yet. |
failed_to_create | The launch failed. |
failed_to_cleanup | A delete failed to clean up after the agent. |
uncertain | The pane could be read, but its end showed no known state. |
errored | The CLI is at rest after an API error ended the last turn. |