komrad

get_agent

Get one agent by id, archived or not, with its prompt in full.

read-onlyidempotentMCP toolAgent

Calling it#

curl -X POST http://127.0.0.1:8787/komrad.agent.v1.AgentService/GetAgent \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "<id>"
}'

Request#

GetAgentRequest#

FieldTypeDescription
iduuid*

The agent to get, by id. Archived agents are included.

Response#

GetAgentResponse#

FieldTypeDescription
agentAgent

The agent, with the prompt in full.

unread_mailbool

Whether mail is waiting that the agent has not read.

pull_requestPullRequestStanding

The state of the current pull request from the agent's branch.

pull_requestsPullRequest[]

Every pull request from the agent's branch, the current one first.

local_review_snapshotsint32

How many review snapshots the agent's work has.

reviewer_commentsCommentCounts

The comments reviewers have left on the agent's work. Unset while there are none.

person_commentsCommentCounts

The comments the person has left on the agent's work. Unset while there are none.

taskTask

The agent's task. Unset for an agent on no task.

forge_commentsCommentCounts

The comments copied from the forge onto the agent's work. Unset while there are none.

Types#

Agent#

Agent is one CLI conversation that komrad runs in a pane and tracks.

FieldTypeDescription
iduuid*

The agent's id. Mail is addressed to it.

namestring

The agent's name. It is also the agent's tmux window name at launch.

cwdstring

The directory of the agent's checkout.

flagsstring

The command-line flags the agent's CLI started with.

promptstring

The agent's prompt.

pane_idstring

The tmux pane the agent's CLI runs in.

stateAgentState

What komrad last read the agent to be doing.

session_idstring

The CLI's own id for the agent's conversation. A resume needs it.

harnessstring

The harness the agent runs, such as claude or codex.

workflow_iduuid*

The id of the workflow the agent belongs to.

created_attimestamp

When the agent was created.

archived_attimestamp

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

schedule_iduuid

The id of the schedule that created the agent. Unset when a person or an agent created it.

alivebool

Whether the agent's pane exists. A dormant agent has none.

idempotency_keystring

The idempotency key the agent's create carried.

spawned_by_agent_iduuid

The id of the agent that created this agent. Unset when the person created it.

failed_runbool

Whether a hook run for the agent failed and the person has not opened its log since.

failed_run_logint32

The id of the log of the agent's failed hook run. Unset when no run failed.

state_changed_attimestamp

When the agent's state last changed.

reported_reasonstring

What the agent's CLI hooks last reported the agent doing.

failure_reasonstring

Why the agent's create or cleanup last failed. Empty when neither has failed.

turn_errorstring

What the CLI printed when an API error ended the agent's last turn. Empty when that turn did not fail.

roleAgentRole

What the agent was launched to do.

task_iduuid

The id of the agent's task. Unset for an orchestrator, or once the task is deleted.

task_slugstring

The slug of the agent's task. Unset whenever task_id is.

provision_disabledbool

Whether the agent was told to work in the workflow's directory instead of a worktree.

hooksstring[]

The CLI hooks the agent's latest launch installed, as the CLI names its events. Empty when that launch failed or never ran.

turn_ended_attimestamp

When the agent's last turn ended. Unset until its first turn ends.

turn_failure_kindTurnFailureKind

Why an error ended the agent's last turn. Unspecified when that turn did not fail.

turn_retriesint32

How many times komrad has retried the agent's failed turns since a turn last ended without an error.

turn_retry_attimestamp

When komrad next retries the agent's failed turn. Unset when no retry is waiting.

PullRequestStanding#

PullRequestStanding is the current pull request from an agent's branch.

FieldTypeDescription
statePullRequestState

The state of the current pull request. unread means komrad has not read the repository yet, and none means the branch has no pull request, or the checkout has moved past a finished one.

numberint32

The current pull request's number. Unset for unread and none.

urlstring

The current pull request's web address. Unset for unread and none.

titlestring

The current pull request's title. Unset for unread and none.

merge_readinessMergeReadiness

Whether the forge would merge the current pull request. Unspecified for unread and none.

head_shastring

The commit at the head of the current pull request on the forge. Unset for unread and none.

forgeKind

The kind of forge the current pull request is on. Unspecified for unread and none.

PullRequest#

PullRequest is a pull request as komrad last read it from the forge.

FieldTypeDescription
iduuid*

The pull request's id.

forgeKind

The kind of forge the pull request is on.

provider_idstring

The forge's own stable id for the pull request, such as GitHub's node_id.

urlstring

The pull request's web address.

repository_urlstring

The web address of the repository the pull request merges into.

head_repository_urlstring

The web address of the repository the pull request's branch is in. Empty when the forge no longer has that repository.

numberint32

The pull request's number, unique within its repository.

titlestring

The pull request's title.

head_branchstring

The branch the pull request merges from.

head_shastring

The commit at the tip of the pull request's branch.

base_branchstring

The branch the pull request merges into.

base_shastring

The commit at the tip of the branch the pull request merges into.

draftbool

Whether the pull request is a draft.

statePullRequestState

The pull request's state.

opened_attimestamp

When the pull request was opened.

changed_attimestamp

When the pull request last changed on the forge.

merged_attimestamp

When the pull request merged. Unset until the pull request merges.

closed_attimestamp

When the pull request closed, merged or not. Unset while the pull request is open.

merge_readinessMergeReadiness

How close the forge is to merging the pull request.

authorstring

The login of the pull request's author. Empty when the forge no longer has the account.

bodystring

The pull request's description. Empty when it has none.

CommentCounts#

CommentCounts counts the comments on an agent's work.

FieldTypeDescription
openint32

How many comments are not resolved, on any snapshot.

resolvedint32

How many comments are resolved, on snapshots that have not landed.

unreadint32

How many comments hold a reply the person has not read.

Task#

Task is one piece of work that agents do.

FieldTypeDescription
iduuid*

The task's id.

workflow_iduuid*

The id of the workflow the task belongs to.

slugstring

The task's slug, such as fix-login. No two tasks ever share one.

titlestring

The task's title.

goalstring

What the task is meant to achieve, in markdown.

created_attimestamp

When the task was created.

updated_attimestamp

When the task last changed.

archived_attimestamp

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

cwdstring

The directory of the task's checkout. Unset while the task has no checkout.

branchstring

The git branch of the task's checkout. Unset when the task has no checkout or git cannot read the branch.

repository_urlstring

The canonical web address of the repository the task's checkout pushes to, such as https://github.com/harrisoncramer/komrad. Unset when the checkout is gone or origin is not on a forge.

head_shastring

The commit checked out in the task's checkout. Unset when the checkout is gone or git cannot read it.

worktree_removal_reasonWorktreeRemovalReason

Why the task's worktree is no longer on disk. Unspecified while it is.

sequenceSequence

The git operation stopped part way in the task's checkout.

moved_since_snapshotstring

The commit of the task's newest snapshot, set while the checkout has changed since that snapshot. Empty otherwise.

diff_statDiffStat

How many lines the task's checkout adds and removes since it left the base branch. Unset when there is no base branch to measure against.

adopted_branchstring

The existing branch the task was put on. Unset when komrad created the branch.

failure_reasonstring

Why the task's last delete failed to remove its checkout. Empty unless a delete failed.

notesstring

The task's notes, in markdown, written by its agents and the person.

notes_updated_attimestamp

When the task's notes were last written, or when the task was created if they never were.

parentParent

The task this task depends on. Unset for a task on the workflow's base branch.

snapshotsint32

How many snapshots komrad has taken of the task's checkout.

guidesint32

How many guides agents have written for the task. list_guides returns them.

MergeReadiness#

MergeReadiness is how close a pull request's head commit is to merging.

FieldTypeDescription
decisionReviewDecision

The forge's review decision.

checksChecks

The state of the checks on the head commit. Unspecified when the forge last reported on an older head.

mergeabilityMergeability

The forge's mergeability, or the last value for the same head while the forge recomputes it.

mergeability_unconfirmedbool

Whether mergeability is the last value for this head, not yet confirmed by a new read.

auto_mergebool

Whether auto-merge is on, so the forge merges once the checks and reviews pass.

auto_mergeablebool

Whether the forge would let komrad turn auto-merge on now. The forge refuses for a draft, a pull request with nothing left to wait for, and a repository that does not allow auto-merge.

credential_approvedbool

Whether komrad's credential has an approval standing on the pull request.

credential_can_approvebool

Whether the forge would take an approval from komrad's credential now. The forge refuses one from the pull request's author and from a user it does not let approve.

reviewersReviewer[]

The users who have reviewed the pull request or have a review request waiting, without its author. Empty before the forge has been read.

DiffStat#

DiffStat counts the lines a checkout adds and removes, committed or not.

FieldTypeDescription
addedint32

How many lines the checkout adds.

removedint32

How many lines the checkout removes.

Parent#

Parent is the task a child depends on, and the fork point where the child's own commits begin on the parent's branch. Snapshots and line counts measure from fork_point.

FieldTypeDescription
task_iduuid*

The id of the parent task.

fork_pointstring

The commit of the parent's branch the child's own commits sit on.

pull_request_iduuid

The id of the parent's pull request, which komrad reads for the parent's newest commit and its merge. Empty until the parent has one.

blockedCascadeBlock

Why the cascade cannot rebase the child onto its parent.

Reviewer#

Reviewer is one user who has reviewed a pull request or been asked to.

FieldTypeDescription
loginstring

The reviewer's login on the forge.

verdictReviewerVerdict

Where the reviewer's latest review leaves them.

requestedbool

Whether a review request to the reviewer is waiting.

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.

AgentRole#

AgentRole is what an agent was launched to do.

ValueDescription
reviewer

An agent on a task that reads the writer's change and gives a review.

orchestrator

The one agent per workflow that hands work out across its tasks.

writer

The one agent on a task that changes its checkout.

TurnFailureKind#

TurnFailureKind is why an error ended an agent's turn, whichever CLI ran it.

ValueDescription
cut_off

The machine slept or the connection dropped mid-response. Komrad retries the turn.

unreachable

The API did not answer after the CLI's own retries. Komrad retries the turn.

rate_limited

The account hit its usage limit. Komrad retries the turn once the limit resets.

other

Any other error, such as a billing or auth error. Komrad does not retry the turn.

PullRequestState#

PullRequestState is the state of a pull request, worked out from the forge's report. A finished state wins over an open one.

ValueDescription
unread

Komrad has not read the repository yet.

none

Komrad read the repository and found no pull request from the branch.

open

Open, without a review decision that decides it.

approved

Open, and the forge would merge it now.

changes_requested

Open, with a reviewer asking for changes.

draft

A draft, whatever its reviews say.

merged

Merged.

closed

Closed without merging.

failing

Open, with a failing check on the head commit, whatever its reviews say.

approved_waiting

Approved, but behind its base branch or blocked by a branch rule.

conflicting

Open, and in conflict with its base branch, whatever its reviews say.

checks_running

Open, with checks running on the head commit and no reviewer asking for changes.

rereview_requested

Open, and every reviewer who asked for changes has been asked to review again.

Kind#

Kind is the kind of forge a host runs.

ValueDescription
github

GitHub, or a GitHub Enterprise host.

gitlab

GitLab, or a self-managed GitLab host.

WorktreeRemovalReason#

WorktreeRemovalReason is why a task's worktree is no longer on disk.

ValueDescription
deleted

A delete removed the worktree. Komrad never makes it again.

gone

Komrad found the worktree's directory gone without a delete.

Sequence#

Sequence is a git operation stopped part way in a task's checkout.

ValueDescription
none

No git operation is stopped part way.

rebase

A rebase stopped on a commit it could not replay.

am

A git am stopped on a patch it could not apply.

merge

A merge stopped on conflicts.

cherry_pick

A cherry-pick stopped on conflicts or paused between commits.

revert

A revert stopped on conflicts or paused between commits.

ReviewDecision#

ReviewDecision is the forge's decision on a pull request's reviews.

ValueDescription
none

The forge reports no decision.

pending

A required review has not been given.

approved

The forge counts the pull request as approved.

changes_requested

A reviewer is asking for changes.

rereview_requested

Every reviewer who asked for changes has been asked to review again.

Checks#

Checks is the overall state of the checks on a pull request's head commit.

ValueDescription
none

The head commit has no checks.

pending

Checks are still running.

passing

Every check passed.

failing

At least one check failed, and every check has finished.

failing_running

At least one check failed, and others are still running.

Mergeability#

Mergeability is whether the forge would merge a pull request, given its base branch and branch rules.

ValueDescription
unknown

The forge has not worked it out yet.

clean

The forge would merge the pull request now.

unstable

Some checks are not passing.

blocked

A branch rule is not met, such as a required review.

behind

The base branch has commits the pull request's branch does not.

conflicting

The branch is in conflict with its base branch.

CascadeBlock#

CascadeBlock is why the cascade cannot rebase a child onto its parent.

ValueDescription
conflicted

Rebasing the child's own commits onto its parent stopped on conflicts.

orphaned

The child is orphaned: its branch holds neither its fork point nor any of its parent's own commits.

parent_closed

The parent's pull request closed without merging.

ReviewerVerdict#

ReviewerVerdict is where one reviewer's latest review of a pull request leaves them.

ValueDescription
none

The reviewer has not reviewed the pull request.

approved

The reviewer approved.

changes_requested

The reviewer asked for changes.

commented

The reviewer left comments without approving or asking for changes.

dismissed

The reviewer's latest review was dismissed.