komrad

list_guides

List the guides written on a task, the caller's task by default, the newest first, each with its guide sections and the snapshot it explains.

read-onlyidempotentMCP toolGuide

Calling it#

curl -X POST http://127.0.0.1:8787/komrad.guide.v1.GuideService/ListGuides \
  -H 'Content-Type: application/json' \
  -d '{}'

Request#

ListGuidesRequest#

FieldTypeDescription
one of

The task whose guides to list. Unset uses the caller's own task.

task_iduuid

The task, by id.

task_slugstring

not empty

The task, by slug.

paginationPagination

The page to read.

Response#

ListGuidesResponse#

FieldTypeDescription
guidesGuide[]

One page of the task's guides, the newest first.

next_page_tokenstring

The cursor for the next page. Unset on the last page.

Types#

Pagination#

Pagination selects one page of a listing.

FieldTypeDescription
limitint32

at least 0

How many records to return. Komrad caps the value, and picks one when unset.

cursorstring

at most 2048 characters

The next_page_token from the previous response. Unset to start from the first page.

Guide#

Guide is a writer's explanation of its diff as it stood at one snapshot, made of guide sections. Guide sections can share lines, and a guide can leave lines out.

FieldTypeDescription
iduuid*

The guide's id.

task_iduuid*

The id of the task whose diff the guide explains.

snapshotReviewSnapshot

The snapshot the guide explains. The guide's line numbers count in the diff from the snapshot's base_sha to its sha.

author_agent_iduuid

The id of the writer that wrote the guide. Unset once that agent was deleted.

created_attimestamp

When the guide was created.

sectionsGuideSection[]

The guide's sections, in the order a reader meets them.

ReviewSnapshot#

ReviewSnapshot is a snapshot of a task's worktree, saved as a commit, that a review is written against. A snapshot never changes.

FieldTypeDescription
iduuid*

The snapshot's id.

task_iduuid*

The id of the task the snapshot was taken of.

ordinalint32

The snapshot's number within its task, counting from one.

base_shastring

The commit on the base branch that the task's branch started from when the snapshot was taken.

shastring

The commit holding the whole worktree, tracked and untracked files alike.

created_attimestamp

When the snapshot was taken.

GuideSection#

GuideSection is one part of a guide: a title, a narrative, and the ranges of lines the narrative talks about.

FieldTypeDescription
titlestring*

at most 200 characters

must not contain control characters

The guide section's title, a short phrase that names what the guide section shows.

narrativestring

at most 4000 characters

The guide section's narrative, markdown that explains in plain sentences how the code in its ranges works, with fenced code blocks drawn highlighted. Empty for a guide section that only points at code.

rangesGuideRange[]

at most 10 items

The ranges of the diff the guide section talks about. Empty for a guide section that only explains.

GuideRange#

GuideRange is a range of lines in one file of the diff a guide explains.

FieldTypeDescription
file_pathstring

must be a relative path without a leading / or ~ or a .. segment

The file's path, relative to the repository root.

old_startint32

at least 0

The first line of the range on the old side of the diff, counting from one. Zero for a range only on the new side.

old_endint32

at least 0

The last line of the range on the old side of the diff.

new_startint32

at least 0

The first line of the range on the new side of the diff, counting from one. Zero for a range only on the old side.

new_endint32

at least 0

The last line of the range on the new side of the diff.

commentstring

at most 2000 characters

What the writer says about the range's lines. Empty for a range with nothing to point out.