komrad

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 '{}'

Request#

Empty#

No fields.

Response#

ListWorktreesResponse#

FieldTypeDescription
worktreesWorktree[]

Every worktree in the worktree directories, in no set order.

dirsstring[]

The worktree directories read: the configured one and each workflow's own.

unreadable_dirsstring[]

The worktree directories that could not be read.

Types#

Worktree#

Worktree is one worktree directory on disk.

FieldTypeDescription
dirstring

The worktree's absolute path.

repo_dirstring

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.

branchstring

The branch checked out in the worktree. Empty when HEAD is detached or git cannot read the worktree.

readablebool

Whether the gitdir that the worktree's .git file names still exists. Git cannot read the worktree without it.

occupantsWorktreeAgent[]

The agents working in the worktree, live ones first.

size_bytesint64

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_attimestamp

When the worktree's size was last measured or last failed to be. Unset until first measured.

size_errorstring

Why the last measurement failed. Empty when it succeeded.

last_active_attimestamp

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.

fateWorktreeFate

What removes the worktree.

share_bytesint64

The worktree's share of size_bytes, with each hard-linked file split evenly across its links. Unset when size_bytes is unset.

taskWorktreeTask

The task the worktree belongs to. Unset when no task owns it.

WorktreeAgent#

WorktreeAgent is an agent working in a worktree.

FieldTypeDescription
iduuid*

The agent's id.

namestring

The agent's name.

stateAgentState

The agent's state.

archived_attimestamp

When the agent was archived. Unset while the agent is live.

WorktreeTask#

WorktreeTask is the task a worktree belongs to.

FieldTypeDescription
iduuid*

The task's id, which is also the worktree directory's name.

slugstring

The task's slug.

archived_attimestamp

When the task was archived. Unset while the task is live.

adoptedbool

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.

ValueDescription
unowned

No task owns the directory. remove_unowned_worktrees removes it.

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.

ValueDescription
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. retry_agent launches the agent again.

failed_to_cleanup

A delete failed to clean up after the agent. failure_reason says why.

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. turn_error names the error.