Read
readRetrieve file content with token-efficient caching: unchanged files return a hash confirmation, changed files return unified diffs, and large files provide outlines or line ranges.
Instructions
Read a file, returning as few tokens as possible. For 2+ files, use batch_read.
The first read returns the file's full content plus a content_hash. Echo
it back as known_hash on every later read: an unchanged file then answers
"unchanged": true with no body, a changed one returns a unified diff, and
without it the file is always sent in full. Reading also caches the file so
grep, search, and batch_read can see it.
A file larger than max_size returns a map instead of its text: the
outline below, or for a file with no definitions its first and last lines
under // L<a>-<b> anchors, flagged truncated with total_lines. Use
offset/limit to read the exact lines it names. A read that returns only
part of a file — a line range, or a map — reports file_hash (prefixed partial:) rather than
content_hash, and it cannot be redeemed as known_hash. A ranged read
also returns a coverage_token: pass it back as known_hash on your next
ranged read and a window you already hold answers unchanged; once the
windows cover the whole file you get a claimable content_hash.
For a large or unfamiliar file, outline=true is the cheap first read: one
line per class/function as <line>: <signature>, and every number is an
offset you can read next. An outline is a map, not the file, so it comes
back as file_hash.
is_diff marks a unified diff and truncated marks a map. 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. | |
| outline | No | Return the file's definitions and their line numbers instead of its text. Cannot be combined with `offset`/`limit`. | |
| max_size | No | Byte threshold above which a map of the file is returned instead of its text; read exact lines with `offset`/`limit`. | |
| known_hash | No | The `content_hash` from your last read of this file — or the `coverage_token` from your last ranged read of it — passed back to get `"unchanged"` instead of the content re-sent. Omit only on a first read, or when you no longer hold what it vouches for. | |
| line_numbers | No | Prefix each line of a ranged read with its number. Costs about 17% more tokens; the range is in `lines` either way. Requires `offset` or `limit`. |