read
Reads a file with minimal tokens by caching its content and returning only diffs when changed. Provide a known hash to skip unchanged data.
Instructions
Read a file, returning as few tokens as possible. For 2+ files, use batch_read.
The first read returns the full numbered content plus a content_hash.
A later read of an unchanged file returns "unchanged": true with no body
(you already have it); a changed file returns a unified diff. Reading also
caches the file so grep, search, and batch_read can see it.
Whenever you re-read a file you have read before, pass back known_hash
(the content_hash from your last read of it). It is the server's only
proof that you still hold the content, so use it every time you can; the
server then skips re-sending unchanged bytes. Use offset/limit to read
or recover an exact line range, for example after a large file was
summarized. A binary file returns metadata instead of content; for images
use read_image.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path (absolute, or relative to the project root). Use an absolute path for files outside the project root. | |
| limit | No | Number of lines to return starting at `offset`. | |
| offset | No | 1-based first line for a ranged read; omit or pass 0 to start from the first line. | |
| max_size | No | Byte threshold above which the file is semantically summarized; recover exact lines afterward with `offset`/`limit`. | |
| known_hash | No | The `content_hash` from your last read of this file; pass it back to get `"unchanged"` instead of the content re-sent. Omit only on a first read or when you no longer hold the hash. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hint | No | ||
| mime | No | ||
| path | No | ||
| size | No | ||
| lines | No | ||
| params | No | ||
| content | No | ||
| is_diff | No | ||
| is_binary | No | ||
| truncated | No | ||
| unchanged | No | ||
| from_cache | No | ||
| total_lines | No | ||
| content_hash | No | ||
| tokens_saved | No | ||
| total_tokens | No | ||
| tokens_original | No | ||
| tokens_returned | No |