komrad

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

Request#

GetWorktreeRequest#

FieldTypeDescription
dirstring*

The worktree to read, by the path list_worktrees returns.

fetchbool

Whether to fetch the base branch from origin before comparing. False compares with the base branch as last fetched.

Response#

GetWorktreeResponse#

FieldTypeDescription
worktreeWorktree

The worktree, as list_worktrees returns it.

entriesEntry[]

The entries at the top of the worktree when it was last measured, largest first. Empty until a measure succeeds.

modifiedstring[]

The tracked paths that differ from HEAD.

untrackedstring[]

The paths git neither tracks nor ignores.

base_refstring

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_errorstring

Why the base branch could not be found. Empty when base_ref is set.

aheadint32

How many of the branch's commits the base branch does not have.

behindint32

How many of the base branch's commits the branch does not have.

landed_commitsint32

How many of the branch's commits have landed, such as after a squash merge.

sequence_in_progressbool

Whether a sequence is stopped in the worktree.

keeps_branchbool

Whether deleting the task keeps the branch. A branch is kept when it was adopted or has commits on no other ref.

commitsCommit[]

The branch's commits the base branch does not have, newest first, at most fifty.

added_linesint32

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_linesint32

How many lines the worktree removes since it left the base branch. Unset when added_lines is unset.

pushedbool

Whether origin has the branch. False when HEAD is detached.

unpushedint32

How many of the branch's commits origin's copy does not have.

unpulledint32

How many of the commits on origin's copy the branch does not have.

unpulled_landedbool

Whether every commit counted in unpulled has landed.

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.

Entry#

Entry is one file or directory in a measured directory, with the largest of what it holds.

FieldTypeDescription
pathstring

The entry's path, relative to the directory or entry holding it.

size_bytesint64

The disk space the entry takes, in bytes, counting blocks and each hard-linked file once.

dirbool

Whether the entry is a directory.

childrenEntry[]

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.

FieldTypeDescription
shastring

The commit's hash.

subjectstring

The first line of the commit's message.

committed_attimestamp

When the commit was made.

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.