Read file contents
catRead one or more files with line numbers, smart truncation, and git ref support. Returns structured output so agents can inspect code across multiple files in a single call.
Instructions
Read one or more files with line numbers and smart truncation. Returns structured output with metadata. Pass path for a single file, or paths to read several in one call (returns { files, count }) — collapsing what would otherwise be multiple round-trips. For large files, use startLine/endLine or maxLines to limit output. Use ref to read from a git branch/commit instead of disk (e.g. ref='main'). NOTE: reading with cat does NOT satisfy the built-in Edit/Write "must read first" guard (it tracks only the built-in Read tool) — run the built-in Read on a file immediately before editing it.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | Git ref to read from (e.g. 'main', 'HEAD~1', a commit hash). When set, reads file content from git (git show ref:path) instead of disk. | |
| path | No | Path to a single file | |
| paths | No | Read multiple files in one call; a string or array. Returns { files, count }; a per-file failure is reported in that file's `error` and does not abort the others. | |
| endLine | No | Stop reading at this line (inclusive) | |
| maxLines | No | Max lines to return per file (default 200, use 0 for unlimited) | |
| startLine | No | Start reading from this line (1-based) | |
| lineNumbers | No | Prepend line numbers to each line (useful when locating a line). Does not register the file as read for the built-in Edit — use the built-in Read right before editing. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| size | No | ||
| count | No | ||
| error | No | ||
| files | No | ||
| mtime | No | File modification time (unix timestamp) | |
| range | No | ||
| content | No | ||
| retained | No | ||
| truncated | No | ||
| totalLines | No |