get_worktree
Read one worktree: its size and largest entries, its uncommitted changes, and how it compares with the base branch.
read-onlyidempotentMCP toolWorktree
Set fetch to fetch from origin first.
Calling it#
curl -X POST http://127.0.0.1:8787/komrad.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 |
|---|---|---|
dir | string* | The worktree to read, by the path |
fetch | bool | Whether to fetch the base branch from origin before comparing. False compares with the base branch as last fetched. |
Response#
GetWorktreeResponse#
| Field | Type | Description |
|---|---|---|
worktree | Worktree | The worktree, as |
entries | Entry[] | The entries at the top of the worktree when it was last measured, largest first. Empty until a measure succeeds. |
modified | string[] | The tracked paths that differ from HEAD. |
untracked | string[] | The paths git neither tracks nor ignores. |
base_ref | string | The ref of the base branch the worktree is compared with. Empty when the repository cannot be read or does not have the base branch, and then no comparison is made. |
base_error | string | Why the base branch could not be found. Empty when |
ahead | int32 | How many of the branch's commits the base branch does not have. |
behind | int32 | How many of the base branch's commits the branch does not have. |
landed_commits | int32 | How many of the branch's commits have landed, such as after a squash merge. |
sequence_in_progress | bool | Whether a sequence is stopped in the worktree. |
keeps_branch | bool | Whether deleting the task keeps the branch. A branch is kept when it was adopted or has commits on no other ref. |
commits | Commit[] | The branch's commits the base branch does not have, newest first, at most fifty. |
added_lines | int32 | How many lines the worktree adds since it left the base branch, without the workflow's diff exclusions. Unset when there is no base branch or it shares no history with the branch. |
removed_lines | int32 | How many lines the worktree removes since it left the base branch. Unset when |
pushed | bool | Whether origin has the branch. False when HEAD is detached. |
unpushed | int32 | How many of the branch's commits origin's copy does not have. |
unpulled | int32 | How many of the commits on origin's copy the branch does not have. |
unpulled_landed | bool | Whether every commit counted in |
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. |
Entry#
Entry is one file or directory in a measured directory, with the largest of what it holds.
| Field | Type | Description |
|---|---|---|
path | string | The entry's path, relative to the directory or entry holding it. |
size_bytes | int64 | The disk space the entry takes, in bytes, counting blocks and each hard-linked file once. |
dir | bool | Whether the entry is a directory. |
children | Entry[] | The largest entries the directory holds, largest first, down to three levels below the measured directory. Empty on a file. |
Commit#
Commit is one git commit.
| Field | Type | Description |
|---|---|---|
sha | string | The commit's hash. |
subject | string | The first line of the commit's message. |
committed_at | timestamp | When the commit was made. |
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. |