list_worktrees

List every worktree directory komrad holds, under the configured worktrees directory and each workflow's own, with the repository it was cut from, its branch, whether git can still read it, the agent it was made for, the other agents working in it, the disk it takes as it was last measured, and when it was last active.

Worktreeread-onlyidempotentMCP tool

A directory with no agent is one whose row was deleted while cleanup did not run, or one a test left behind. A directory a delete has claimed and not yet taken, through delete_agents, delete_worktrees or the panel, is left out until that delete fails. Sizes are measured in the background a few directories at a time, so a directory the loop has not reached yet carries none. This reads the directories, the agent rows and the stored sizes and runs no git, so it is cheap to call often; read one directory's contents and standing against its base with get_worktree, which also measures it afresh.

Calling it#

curl -X POST http://127.0.0.1:8787/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`	list of Worktree	Every directory under the worktree directories, in no particular order.
`dirs`	list of string	The directories that were walked: the configured one and each workflow's own.
`unreadableDirs`	list of string	Which of those could not be read, so a listing that is short says why.

Types#

Worktree#

Field	Type	Description
`dir`	string	The directory, absolute.
`repoDir`	string	The repository the worktree was cut from, read off the directory's own .git file, which for a registration git can no longer read is where the repository used to be.
`branch`	string	The branch the directory's HEAD names, empty when it is detached or the registration cannot be read.
`readable`	bool	Whether the gitdir the .git file names is still there, without which git will not answer for the directory.
`agent`	WorktreeAgent	The agent the directory was made for, unset when no row answers for it.
`occupants`	list of WorktreeAgent	The other agents working in this directory, which hold none of their own.
`sizeBytes`	int64	The disk the directory takes, in bytes, as it was last measured in the background or by get_worktree: blocks rather than length, a hard linked file counted once. Unset until it has been measured, and while the last walk failed.
`measuredAt`	string	When the size was last measured, or last failed to be, in RFC 3339. Unset until the background loop has reached the directory.
`sizeError`	string	Why the last walk failed, empty when it did not.
`lastActiveAt`	string	When the directory was last active, in RFC 3339: the later of its agent's last state change and its archiving when an agent answers for it, else when git last wrote the directory's .git file, else the directory's own modification time.
`fate`	WorktreeFate	Which delete path the directory takes.

WorktreeAgent#

Field	Type	Description
`id`	string	The agent's id.
`name`	string	What the panel lists it as.
`state`	AgentState	The agent's state, as the agents listing carries it.
`archivedAt`	string	When the agent was put away, in RFC 3339, unset while it is live.
`adopted`	bool	Whether the branch was somebody's before the agent was put on it, which cleanup never deletes.

WorktreeFate#

WorktreeFate is which delete path a directory takes.

Value	Description
`WORKTREE_FATE_UNOWNED`	Nothing answers for the directory, which the remover takes.
`WORKTREE_FATE_ARCHIVED`	The directory's agent is put away, which the agent delete takes.
`WORKTREE_FATE_LIVE`	The directory's agent is running, which nothing takes.

AgentState#

AgentState is what the panel last decided an agent was doing, read off the tail of its pane.

Value	Description
`AGENT_STATE_IDLE`	The pane is at rest with nothing typed.
`AGENT_STATE_THINKING`	The CLI is working on a turn.
`AGENT_STATE_WAITING`	The CLI is blocked on a human answering a selection.
`AGENT_STATE_SETTING_UP`	The agent is being launched and has no pane to read yet.
`AGENT_STATE_FAILED_TO_CREATE`	The launch failed, which retry_agent is for.
`AGENT_STATE_FAILED_TO_CLEANUP`	A delete failed to take the worktree down, and the reason is on the row.
`AGENT_STATE_UNCERTAIN`	The pane could be read but its tail decided nothing.