Read#
Read the contents of one or more files, or list the contents of a directory.
Provides a sandboxed file reading capability that works without shell access.
Useful for restricted tool sets (e.g., --tools read,patch,save).
Multiple paths can be passed in the code block (one per line) to read several files in a single tool call, reducing roundtrips when exploring a codebase.
Instructions
Read the content of one or more files, or list the contents of a directory.
Paths can be relative or absolute.
For files, output includes line numbers for easy reference.
For directories, output shows a flat listing of immediate files and subdirectories.
### When to use read
Reading a file directly gives you its exact, current content with line numbers —
eliminating guesswork from memory, file names, or comments. Prefer `read` over
those shortcuts when the file itself is the source of truth.
To read multiple files in a single call, put one path per line in the code block.
Lines beginning with '#' are treated as comments and skipped.
The line-range parameters (start_line, end_line) only apply when reading a single file.
For files over 1 MiB, always supply start_line and end_line to read a section at a
time; advance start_line to the next line after the shown range to paginate through
the file. hashline_edit is not available for large-file ranged reads; use the save
or patch tool to edit large files.
Examples
| User |
read hello.py |
| Assistant |
|
| System |
```hello.py
> 1 print("Hello world")
> 2 print("Goodbye world")
> ```
|
| User |
read both source files |
| Assistant |
|
| System |
```hello.py
> 1 print("Hello world")
> ```
> ```goodbye.py
> 1 print("Goodbye world")
> ```
|