# get\_guide

Get one guide by id, with every narrative and comment whole.

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/GetGuide \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "<id>"
}'
```

```bash
komrad rpc get-guide \
  --id '<uuid>'
```

```json
{
  "name": "get_guide",
  "arguments": {
    "id": "<id>"
  }
}
```

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

## Request

### GetGuideRequest

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/guide/get-guide.md#komrad-guide-v1-GetGuideRequest-id) | uuid\* | The guide to get, by id. |

## Response

### GetGuideResponse

| Field | Type | Description |
| --- | --- | --- |
| [`guide`](https://komrad.dev/latest/api/guide/get-guide.md#komrad-guide-v1-GetGuideResponse-guide) | [Guide](https://komrad.dev/latest/api/guide/get-guide.md#komrad-guide-v1-Guide) | The guide, with every narrative and comment whole. |

## Types

### 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/get-guide.md#komrad-guide-v1-Guide-id) | uuid\* | The guide's id. |
| [`task_id`](https://komrad.dev/latest/api/guide/get-guide.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/get-guide.md#komrad-guide-v1-Guide-snapshot) | [ReviewSnapshot](https://komrad.dev/latest/api/guide/get-guide.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/get-guide.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/get-guide.md#komrad-guide-v1-Guide-created_at) | timestamp | When the guide was created. |
| [`sections`](https://komrad.dev/latest/api/guide/get-guide.md#komrad-guide-v1-Guide-sections) | [GuideSection\[\]](https://komrad.dev/latest/api/guide/get-guide.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/get-guide.md#komrad-agent-v1-ReviewSnapshot-id) | uuid\* | The snapshot's id. |
| [`task_id`](https://komrad.dev/latest/api/guide/get-guide.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/get-guide.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/get-guide.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/get-guide.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/get-guide.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/get-guide.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/get-guide.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/get-guide.md#komrad-guide-v1-GuideSection-ranges) | [GuideRange\[\]](https://komrad.dev/latest/api/guide/get-guide.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/get-guide.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/get-guide.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/get-guide.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/get-guide.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/get-guide.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/get-guide.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. |
