Read
readRetrieve file contents with intelligent caching: unchanged files return no body, modified files return only a diff, and large files can be summarized, outlined, or read by line range.
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.
Use offset/limit to read an exact line range, for example after a large
file was summarized. A read that returns only part of a file — a line
range, or a summary — 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 summary. 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 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 — 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`. |