# 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-only · idempotent · MCP tool · [Guide](https://komrad.dev/latest/api/guide.md)

## Calling it

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

```bash
komrad rpc list-guides
```

```json
{
  "name": "list_guides",
  "arguments": {}
}
```

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

## Request

### ListGuidesRequest

| Field | Type | Description |
| --- | --- | --- |
| [one of](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-ListGuidesRequest-task) |  | The task whose guides to list. Unset uses the caller's own task. |
| [`task_id`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-ListGuidesRequest-task_id) | uuid | The task, by id. |
| [`task_slug`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-ListGuidesRequest-task_slug) | string not empty | The task, by slug. |
| [`pagination`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-ListGuidesRequest-pagination) | [Pagination](https://komrad.dev/latest/api/guide/list-guides.md#komrad-pagination-v1-Pagination) | The page to read. |

## Response

### ListGuidesResponse

| Field | Type | Description |
| --- | --- | --- |
| [`guides`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-ListGuidesResponse-guides) | [Guide\[\]](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-Guide) | One page of the task's guides, the newest first. |
| [`next_page_token`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-ListGuidesResponse-next_page_token) | string | The cursor for the next page. Unset on the last page. |

## Types

### Pagination

Pagination selects one page of a listing.

| Field | Type | Description |
| --- | --- | --- |
| [`limit`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-pagination-v1-Pagination-limit) | int32 at least 0 | How many records to return. Komrad caps the value, and picks one when unset. |
| [`cursor`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-pagination-v1-Pagination-cursor) | string 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.

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-Guide-id) | uuid\* | The guide's id. |
| [`task_id`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-Guide-task_id) | uuid\* | The id of the task whose diff the guide explains. |
| [`snapshot`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-Guide-snapshot) | [ReviewSnapshot](https://komrad.dev/latest/api/guide/list-guides.md#komrad-agent-v1-ReviewSnapshot) | 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_id`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-Guide-author_agent_id) | uuid | The id of the writer that wrote the guide. Unset once that agent was deleted. |
| [`created_at`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-Guide-created_at) | timestamp | When the guide was created. |
| [`sections`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-Guide-sections) | [GuideSection\[\]](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-GuideSection) | 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.

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-agent-v1-ReviewSnapshot-id) | uuid\* | The snapshot's id. |
| [`task_id`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-agent-v1-ReviewSnapshot-task_id) | uuid\* | The id of the task the snapshot was taken of. |
| [`ordinal`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-agent-v1-ReviewSnapshot-ordinal) | int32 | The snapshot's number within its task, counting from one. |
| [`base_sha`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-agent-v1-ReviewSnapshot-base_sha) | string | The commit on the base branch that the task's branch started from when the snapshot was taken. |
| [`sha`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-agent-v1-ReviewSnapshot-sha) | string | The commit holding the whole worktree, tracked and untracked files alike. |
| [`created_at`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-agent-v1-ReviewSnapshot-created_at) | timestamp | 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.

| Field | Type | Description |
| --- | --- | --- |
| [`title`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-GuideSection-title) | string\* at most 200 characters must not contain control characters | The guide section's title, a short phrase that names what the guide section shows. |
| [`narrative`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-GuideSection-narrative) | string 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. |
| [`ranges`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-GuideSection-ranges) | [GuideRange\[\]](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-GuideRange) 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.

| Field | Type | Description |
| --- | --- | --- |
| [`file_path`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-GuideRange-file_path) | string must be a relative path without a leading / or ~ or a .. segment | The file's path, relative to the repository root. |
| [`old_start`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-GuideRange-old_start) | int32 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_end`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-GuideRange-old_end) | int32 at least 0 | The last line of the range on the old side of the diff. |
| [`new_start`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-GuideRange-new_start) | int32 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_end`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-GuideRange-new_end) | int32 at least 0 | The last line of the range on the new side of the diff. |
| [`comment`](https://komrad.dev/latest/api/guide/list-guides.md#komrad-guide-v1-GuideRange-comment) | string at most 2000 characters | What the writer says about the range's lines. Empty for a range with nothing to point out. |
