read_file
Read text files as numbered lines, with line-range windows or in-file pattern search. Returns line numbers plus mtime and SHA-256 for safe concurrent edits.
Instructions
Read the text contents of a file (absolute path, file:// URI, or workspace-relative path). Use start_line/end_line to stream a slice of a large file. Each line is prefixed with a 1-based line number + tab (cat -n style) for exact range math; this gutter is display-only — strip the leading '\t' before reusing a line as an edit_file/find_replace old_string. Binary files are rejected; output is capped at 200 KiB (use line ranges on large files). The header carries the file's mtime (RFC3339Nano) and SHA-256 — pass them back as expected_mtime/expected_sha on edit_file for optimistic-concurrency checks. Pass pattern to search WITHIN the file instead of windowing: it returns each matching line with its 1-based line number (and optional context_lines), so an over-cap file stays searchable in one tool — literal text by default (smart-case: case-insensitive when all lowercase), Go RE2 regex when use_regex; output is bounded by max_matches (default 200) and labelled when truncated. Combine pattern with start_line/end_line to restrict the search to a line window; pattern with limit is rejected.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of lines to return starting at the first line (Claude Code-style window; first line defaults to 1). Mutually exclusive with end_line. Not usable together with pattern (search mode) — use max_matches instead. | |
| offset | No | First line to read, 1-based (Claude Code-style alias for start_line; start_line wins if both are given). | |
| pattern | No | Search the file for this pattern instead of returning a window: returns each matching line with its 1-based line number (and optional context), bounded output. Literal text by default; a regular expression when use_regex is true. The whole file is scanned line-by-line regardless of size, so an over-cap file stays searchable. Combine with start_line/end_line to restrict the search to that line window; not usable with limit. | |
| end_line | No | Last line to return (1-based, inclusive). Omit to read to the end of the file. | |
| file_path | No | Absolute path, file:// URI, or workspace-relative path of the file to read. | |
| use_regex | No | Treat pattern as a Go RE2 regular expression. Default false — pattern is literal text. Only consulted when pattern is set. | |
| start_line | No | First line to return (1-based, inclusive). Omit to start from the beginning. | |
| max_matches | No | Maximum number of matching lines to return in search mode. Default 200. Output is truncated (and labelled) beyond this. Only consulted when pattern is set. | |
| context_lines | No | Lines of context to show before and after each match (like rg -C). Default 0. Only consulted when pattern is set. | |
| case_sensitive | No | Force case-sensitive matching for pattern. Default (omitted): smart-case — case-insensitive when pattern is all lowercase, case-sensitive otherwise. Pass false to force case-INSENSITIVE matching even for an uppercase pattern. Only consulted when pattern is set. |