list_agents

List the agents the panel tracks, live and dormant, with each one's name, state, working directory, flags, and workflow.

Agentread-onlyidempotentMCP tool

Archived agents are excluded unless archived is set, which lists those and only those. Returns one page, most recently updated first; pass the response's nextPageToken back as pagination.cursor for the next one. The summary this returns by default holds only the opening of each agent's prompt, marked by promptTruncated; get_agent returns one whole, and view VIEW_FULL returns every prompt on the page at the cost of a very large reply. Start here to find the id or name another tool needs.

Calling it#

curl -X POST http://127.0.0.1:8787/agent.v1.AgentService/ListAgents \
  -H 'Content-Type: application/json' \
  -d '{}'

komrad rpc list-agents

{
  "name": "list_agents",
  "arguments": {}
}

Offered by the komrad MCP server to implementer, reviewer, orchestrator agents.

Request#

ListAgentsRequest#

Field	Type	Description
`pagination`	Pagination	Where to carry on from.
`archived`	bool	True to list the archived agents and only those.
`view`	View	How much of each record to return, since the panel draws every field and a model reading the same endpoint has a context window to spend.

Response#

ListAgentsResponse#

Field	Type	Description
`agents`	list of AgentRow	One page of agents, newest first, each with what is drawn beside it.
`nextPageToken`	string	Pass this back as the pagination cursor for the next page.

Types#

Pagination#

Field Type Description

Field	Type	Description
`limit`	int32	How many rows to return, capped by the server, and left to the server entirely when unset.
`cursor`	string	The next_page_token a previous reply carried, or unset to start from the beginning. at most 2048 characters

limit

int32

How many rows to return, capped by the server, and left to the server entirely when unset.

cursor

string

The next_page_token a previous reply carried, or unset to start from the beginning.

at most 2048 characters

AgentRow#

AgentRow is an agent with what is drawn beside it: its mark, its waiting mail and the pull requests on its branch, assembled from those resources.

Field	Type	Description
`agent`	Agent	The agent itself.
`mark`	string	The letter a person jumps to it by in the panel, if it holds one.
`unreadMail`	bool	Whether mail is waiting that it has not taken.
`pullRequest`	PullRequestStanding	Where the pull request opened from its branch stands.
`pullRequests`	list of PullRequest	Every pull request opened from its branch, the current one first.
`localReviewRounds`	int32	How many rounds of local review its own work has been through.
`localReviewVerdict`	ReviewVerdict	What the last released local review concluded about the agent's own work, UNSPECIFIED when none has concluded anything.
`localReviewTree`	ReviewTreeStanding	Where the agent's worktree stands against the round that verdict was given on.

Agent#

Field	Type	Description
`id`	string	The handle every other call names this agent by, and what mail is addressed to.
`name`	string	What the panel lists it as, which is also its tmux window name at launch.
`cwd`	string	The directory it is running in, its own worktree when the workflow provisions one.
`flags`	string	The command-line flags its CLI was started with.
`prompt`	string	The whole briefing it was launched with.
`paneId`	string	The tmux pane its CLI is running in, which is what capture-pane reads.
`state`	AgentState	What the panel last decided it was doing, read off the tail of its pane.
`sessionId`	string	The CLI's own conversation id, which is the handle a resume needs.
`harness`	string	Which CLI it runs, such as claude or codex.
`workflowId`	string	Which workflow it is filed under, whose context it took at launch.
`createdAt`	string	When it was launched, in RFC 3339.
`archivedAt`	string	When it was hidden from the panel, unset while it is live.
`scheduleId`	string	The schedule that launched it, unset for an agent a person or another agent spawned.
`alive`	bool	Whether its pane is still there, which a dormant agent's is not.
`hidden`	bool	Whether the panel draws a row for it, which changes nothing about the agent itself.
`metadata`	list of AgentMetadata	Facts it has recorded about its own work, such as the ticket it is implementing.
`idempotencyKey`	string	The key a retry of its create carried, which is what answers a repeat with this agent.
`spawnedByAgentId`	string	Which agent called create, unset for one a person spawned.
`parentAgentId`	string	The agent this one is attached to, where spawned_by_agent_id is only who called create.
`branch`	string	The git branch its worktree is on, unset for an agent that provisions none.
`repositoryUrl`	string	The canonical web address of the repository its checkout pushes to, such as https://github.com/harrisoncramer/komrad, unset when the checkout is gone or its origin is not a forge.
`headSha`	string	The commit its checkout has checked out, unset when the checkout is gone or git cannot read it.
`worktreeRemoved`	bool	Whether its checkout has been taken away, which leaves the record and the transcript.
`sequenceInProgress`	bool	Whether a merge, a rebase or a cherry-pick is part-way through its checkout, waiting on somebody to settle it.
`failedRun`	bool	Whether a script komrad fired for the agent failed and nobody has looked at it since.
`failedRunLog`	int32	The run log that failure was written to, which is the run the panel opens on.
`stateChangedAt`	string	When the state above last moved, in RFC 3339.
`reportedReason`	string	What the agent's own CLI last reported it was doing, which annotates the state the pane decided rather than replacing it.
`role`	AgentRole	What the agent was launched to do, which decides the half of the review briefing it is sent.
`promptTruncated`	bool	Whether prompt holds only its opening, which a summary listing returns so that a page of agents does not carry every briefing they were launched with.
`treeStanding`	ReviewTreeStanding	Where the agent's worktree stood when last measured against the round tree_standing_sha names.
`treeStandingSha`	string	The snapshot of the round tree_standing was measured against, empty before any measurement.
`movedSinceRound`	string	The snapshot of its newest round while its worktree no longer hashes to it, empty otherwise.
`heldAt`	string	When a person stopped this agent and took its worktree, empty while nobody is holding it.

PullRequestStanding#

Field	Type	Description
`state`	PullRequestState	Where the current pull request stands: UNREAD when the repository has not been read, NONE when it has and nothing was opened from the branch, else the state of the current one.
`number`	int32	The number of the current pull request, unset for UNREAD and NONE.
`url`	string	The web address of the current pull request, unset for UNREAD and NONE.
`title`	string	The title of the current pull request, unset for UNREAD and NONE.
`checks`	Checks	Where the checks on the current pull request's head stand, UNSPECIFIED for UNREAD and NONE.
`mergeability`	Mergeability	Where the forge says the current pull request stands against its base and rules, UNSPECIFIED for UNREAD and NONE.

PullRequest#

Field	Type	Description
`id`	string	The handle komrad keys the row by.
`forge`	string	Which forge it lives on, such as github.
`providerId`	string	The forge's own stable identifier, such as GitHub's node_id.
`url`	string	The web address a person opens.
`repositoryUrl`	string	The canonical address of the repository it targets.
`headRepositoryUrl`	string	The canonical address of the repository its branch lives in, empty when the forge no longer has it.
`number`	int32	The number the forge shows a person, which is per repository.
`title`	string	The title as the forge has it.
`headBranch`	string	The branch the pull request was opened from.
`headSha`	string	The commit at the tip of that branch when last read.
`baseBranch`	string	The branch it targets.
`baseSha`	string	The commit the target branch was at when last read.
`draft`	bool	Whether the forge marks it a draft.
`state`	PullRequestState	Where it stands, decided from the stored row.
`openedAt`	string	When it was opened on the forge, in RFC 3339.
`changedAt`	string	When the forge last saw it change, in RFC 3339.
`mergedAt`	string	When it merged, in RFC 3339, unset while it has not.
`closedAt`	string	When it closed, in RFC 3339, unset while it is open; a merged one carries this too.
`reviewDecision`	ReviewDecision	Where the forge says the reviews stand.
`checks`	Checks	Where the checks on its head stand.
`mergeability`	Mergeability	Where the forge says it stands against its base and rules.

AgentMetadata#

Field	Type	Description
`key`	string	What the fact is filed under, such as pr or branch.
`value`	string	The fact as the panel shows it, which is why a URL belongs here whole.

View#

View is how much of each record a listing returns, so that the panel, which draws every field, and a model reading the same endpoint through a context window ask for different amounts of the same rows.

Value	Description
`VIEW_SUMMARY`	Long text is cut to its opening, and the record says which fields were cut.
`VIEW_FULL`	Every field whole, however long.

ReviewVerdict#

ReviewVerdict is what an author concluded about a round, which is what tells the agent whether it is done rather than leaving it to read that out of the prose.

Value	Description
`REVIEW_VERDICT_APPROVED`	This round is good as it stands.
`REVIEW_VERDICT_CHANGES_REQUESTED`	The agent should keep working.
`REVIEW_VERDICT_COMMENTED`	Notes without a conclusion either way.

ReviewTreeStanding#

ReviewTreeStanding is where an agent's worktree stands against the round its last verdict was given on.

Value	Description
`REVIEW_TREE_STANDING_MOVED`	The worktree differs from the round and the base does not hold the round.
`REVIEW_TREE_STANDING_LANDED`	The base holds the round whole and the worktree carries nothing beyond the base.
`REVIEW_TREE_STANDING_LANDED_MOVED`	The base holds the round whole and the worktree carries new work on top of the base.

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.

AgentRole#

AgentRole is what an agent was launched to do.

Value	Description
`AGENT_ROLE_IMPLEMENTER`	An agent that lands work on a branch of its own.
`AGENT_ROLE_REVIEWER`	A child that reads another agent's work and gives a review.
`AGENT_ROLE_ORCHESTRATOR`	The agent drawn on a workflow's own row that hands work out.

PullRequestState#

PullRequestState is where a stored pull request stands, decided on the server from its stamps, its draft flag, the checks on its head, its mergeability and the forge's review decision, finished first.

Value	Description
`PULL_REQUEST_STATE_UNREAD`	The repository's first sweep has not completed, so nothing is known.
`PULL_REQUEST_STATE_NONE`	The repository has been swept and nothing was opened from the branch.
`PULL_REQUEST_STATE_OPEN`	Open with no review decision that settles it.
`PULL_REQUEST_STATE_APPROVED`	Open and the forge would merge it now: its rules on reviews and checks are met and the branch is level with its base.
`PULL_REQUEST_STATE_CHANGES_REQUESTED`	Open with a reviewer asking for changes.
`PULL_REQUEST_STATE_DRAFT`	Still a draft, whatever its reviews say.
`PULL_REQUEST_STATE_MERGED`	Merged.
`PULL_REQUEST_STATE_CLOSED`	Closed without merging.
`PULL_REQUEST_STATE_FAILING`	Open with a failing check on its head, whatever its reviews say.
`PULL_REQUEST_STATE_APPROVED_WAITING`	Approved on the forge but not yet mergeable: its checks are still running, its branch is behind, or a branch rule is unmet.
`PULL_REQUEST_STATE_CONFLICTING`	Open and no longer merging cleanly into its base, whatever its reviews say.

Checks#

Checks is where the checks on a pull request's head commit stand, as the forge last reported them.

Value	Description
`CHECKS_NONE`	The forge reports no checks on the head.
`CHECKS_PENDING`	A run is still in flight.
`CHECKS_PASSING`	Every check passed.
`CHECKS_FAILING`	At least one check failed.

Mergeability#

Mergeability is where the forge says a pull request stands against its base and its branch rules, as it last computed it.

Value	Description
`MERGEABILITY_UNKNOWN`	The forge has not computed it yet.
`MERGEABILITY_CLEAN`	The forge would merge it now.
`MERGEABILITY_UNSTABLE`	Its checks are not all passing.
`MERGEABILITY_BLOCKED`	A branch rule is unmet, such as a required review.
`MERGEABILITY_BEHIND`	The base has moved past the branch.
`MERGEABILITY_CONFLICTING`	The branch no longer merges cleanly into its base.

ReviewDecision#

ReviewDecision is where a forge says a pull request's reviews stand.

Value	Description
`REVIEW_DECISION_NONE`	The forge has said nothing about the reviews.
`REVIEW_DECISION_PENDING`	A review the forge requires that nobody has given.
`REVIEW_DECISION_APPROVED`	The forge counts the pull request as approved.
`REVIEW_DECISION_CHANGES_REQUESTED`	A reviewer is asking for changes.