get_worktree

Read one worktree directory: its size and its top-level entries with theirs, biggest first, walked for the call and recorded so list_worktrees carries the fresh number, what is uncommitted, the base it is measured against with how far ahead and behind it stands and how many of its commits the base already holds whole, whether deleting its agent would keep the branch, and the commits since the base.

Worktreeread-onlyidempotentMCP tool

The base is read as the clone last fetched it unless fetch is set, which asks origin first. A directory whose registration git cannot read answers with the entries alone.

Calling it#

curl -X POST http://127.0.0.1:8787/worktree.v1.WorktreeService/GetWorktree \
  -H 'Content-Type: application/json' \
  -d '{
  "dir": "<dir>"
}'

komrad rpc get-worktree \
  --dir <string>

{
  "name": "get_worktree",
  "arguments": {
    "dir": "<dir>"
  }
}

Offered by the komrad MCP server to orchestrator agents.

Request#

GetWorktreeRequest#

Field Type Description

Field	Type	Description
`dir`	string	The directory to read, as list_worktrees spelled it. required
`fetch`	bool	Whether to fetch the base from origin before measuring against it, which is a network round trip; left off, the base is whatever the clone last fetched.

dir

string

The directory to read, as list_worktrees spelled it.

required

fetch

bool

Whether to fetch the base from origin before measuring against it, which is a network round trip; left off, the base is whatever the clone last fetched.

Response#

GetWorktreeResponse#

Field	Type	Description
`worktree`	Worktree	The directory as list_worktrees reports it.
`sizeBytes`	int64	The disk the directory takes, in bytes, walked for this call.
`entries`	list of Entry	The top-level entries with the disk each takes, biggest first, from the same walk.
`modified`	list of string	The paths git tracks that differ from HEAD.
`untracked`	list of string	The paths git neither tracks nor ignores.
`baseRef`	string	The ref the branch is measured against, which is the workflow's base branch as the clone holds it, empty when the repository cannot be read or the clone does not hold the base, in which case nothing below is measured.
`baseError`	string	Why the base could not be named, when base_ref is empty for that reason.
`ahead`	int32	How many of the branch's commits the base does not hold.
`behind`	int32	How many of the base's commits the branch does not hold.
`landedCommits`	int32	How many of the branch's own commits the base already holds whole, which is what a squash merge leaves behind.
`sequenceInProgress`	bool	Whether a merge, a rebase or a cherry-pick is part-way through.
`keepsBranch`	bool	Whether deleting the agent would keep the branch, which cleanup does for an adopted branch and for one whose commits are on no other ref.
`commits`	list of Commit	The branch's commits the base does not hold, newest first, at most fifty.

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.

Entry#

Field	Type	Description
`path`	string	The path, relative to the directory.
`sizeBytes`	int64	The disk it takes, in bytes, counted through for a directory: blocks rather than length, with a file that is hard linked counted once.
`dir`	bool	Whether it is a directory.

Commit#

Field	Type	Description
`sha`	string	The commit's hash.
`subject`	string	The first line of its message.
`committedAt`	string	When it was committed, in RFC 3339.

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.