> ## Documentation Index
> Fetch the complete documentation index at: https://agent-harness101.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reading large files

> How can an agent inspect a file that is too large for its context?

## The new problem

If a file contains 20,000 lines, does `read_file` send all 20,000 lines to the model?

**No—not necessarily.** `read_file` is a name, not a standard API. An implementation might return the entire file, a requested range, or a capped excerpt. The model only sees the content the harness includes in its observation. Reading bytes on disk and putting those bytes into the model's context are separate operations.

For this guide, use **bounded reads with explicit continuation**, and search for relevant code before expanding the context.

> [!NOTE]
>
> The contracts and limits below are a proposed design for this guide, not an industry standard. For how two production agents bound their reads, see the comparison table in [Essential tools](/tools/essential-tools#which-tools-are-must-haves).

## Will read\_file read the whole file?

Only when the implementation allows it and the file fits the budget. A useful contract accepts a range and applies a hard output cap even if the caller asks for more.

```json theme={null}
{
  "path": "src/auth/session.ts",
  "start_line": 120,
  "max_lines": 80,
  "max_output_bytes": 16384
}
```

In this example, lines are **one-based**, `max_lines` is a count, and the byte limit applies to the returned content. The harness validates and clamps these values. The caller cannot disable the hard maximum by passing an enormous number.

An illustrative response for a large file could be:

```json theme={null}
{
  "path": "src/auth/session.ts",
  "file_version": "sha256:example-version",
  "start_line": 120,
  "end_line": 199,
  "content": "120: export function validateSession(...) { ... }\n...",
  "truncated": true,
  "truncation_reason": "line_limit",
  "next_start_line": 200,
  "eof": false
}
```

The content above is abbreviated for display. A real tool returns the exact requested text, not an invented summary. `truncated` here means that unread content remains after the returned range; `eof` means the read reached the end of the file. Keeping these semantics explicit prevents “I read the file” from silently meaning “I saw its first few lines.”

### What limits should we start with?

As an initial policy, try 200 lines and 16 KiB of content per read, whichever is reached first. These are design examples to tune against real tasks, not proven optimal values. Reserve context for the user request, prior observations, reasoning, and the response. A byte cap is not a token cap: also enforce the model's total input budget when assembling context.

Return complete lines where possible. If a single minified line exceeds the cap, return a structured `line_too_long` error with a recovery hint, or use a separate byte-range reader with a byte cursor. Advancing to the next line after returning half a line would silently lose content.

Do not compute an exact total line count on every read if doing so requires scanning a huge file. A reliable continuation cursor and `eof` are enough. Small files can be returned in full when they fit the same limits.

## How does the agent understand a large file?

It builds evidence incrementally. It does not need every line for every task, but a small excerpt is not proof of whole-file understanding.

```mermaid theme={null}
flowchart TD
  Task["Locate the behavior to change"] --> Find["Find candidate paths"]
  Find --> Search["Search symbols, errors, or call sites"]
  Search --> Read["Read bounded ranges around matches"]
  Read --> Enough{"Enough evidence?"}
  Enough -->|No| Expand["Read surrounding definitions and dependencies"]
  Expand --> Read
  Enough -->|Yes| Edit["Apply a targeted patch"]
  Edit --> Verify["Inspect diff and run relevant checks"]
```

### Example: a session expires too early

1. Use `find_files` for likely auth or session paths. Avoid dumping the entire repository tree.
2. Search those paths for `expiresAt`, the observed error, or the validation function. Return a bounded number of matches with line numbers.
3. Read the complete relevant function around the best match. If the range cuts through the function, expand it.
4. Inspect the timestamp type, configuration, callers, and nearby tests. A conversion bug may live outside the first matching file.
5. Patch the smallest justified change, review the diff, and run the relevant tests. Report what was verified and what remains uncertain.

For a broad refactor, more of the repository may be necessary. Retrieve additional ranges deliberately and keep concise notes with paths and line references. Summaries help navigation; reread the exact current source before editing it. If the task requires a whole-file audit, track coverage explicitly and do not claim completion after sampling.

## What makes reading reliable?

Resolve paths inside the authorized workspace, including symlink targets. Identify missing, binary, unsupported, or unreadable files explicitly. Avoid sending binary data as if it were text.

Attach a file version to every read, so a later edit can check that the file has not changed since. [Edit & run tools in detail](/tools/edit-and-run-tools) covers how edits use it.

## How do we know the design works?

Exercise the read contract with a small file, a huge file, an oversized single line, an empty file, and a binary file.

Check that every case either returns bounded, accurate content with a way to continue, or fails explicitly. Then evaluate actual tasks: can the agent find the relevant part of a large file without repeatedly retrieving irrelevant content?

> [!TIP]
>
> **Design decision:** Bound every read, report whether content remains, and search before expanding. Never let a partial read pass for a whole-file read.

## Sources and further reading

Anthropic's [Writing effective tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents) recommends pagination, range selection, filtering, and truncation for large responses. The contracts and worked example on this page are this guide's proposed implementation.

## Continue learning

> **[Repository access](/tools/repository-access)**
>
> Return to the topic that introduced read\_file.

> **[Harness controls](/advanced/harness-controls)**
>
> The next advanced topic: how the harness decides which actions run.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.