API: file content

The Read tool lets Theus read the contents of any file on the local filesystem — text, images, PDFs and Jupyter notebooks — as a first-class, read-only tool capability.

Overview

Theus exposes file reading as the Read tool. It is read-only and concurrency-safe, so it can run in parallel with other reads. Given an absolute path, it returns the file contents formatted for the model. Text files come back with line numbers (cat -n style, starting at line 1); images, PDFs and notebooks are decoded into their native multimodal representations.

The tool reads files only, not directories. To list a directory, run an ls command through the Bash tool instead.

Inputs

The tool accepts a strict object with the following parameters:

Parameter	Type	Required	Description
`file_path`	string	Yes	The absolute path to the file to read. Relative paths are not accepted; `~` is expanded internally.
`offset`	integer (≥ 0)	No	The line number to start reading from. Only provide it if the file is too large to read at once.
`limit`	integer (> 0)	No	The number of lines to read. Only provide it if the file is too large to read at once.
`pages`	string	No	Page range for PDF files (e.g. `"1-5"`, `"3"`, `"10-20"`). Pages are 1-indexed. Only applies to PDFs; maximum 20 pages per request.

By default the tool reads up to 2000 lines from the beginning of the file. When you already know which part of a large file you need, pass offset and limit to read just that slice.

Output types

The result is discriminated by a type field. Depending on the file, one of the following is returned:

Type	Returned for	Payload
`text`	Text/source files	Content with line numbers, plus `numLines`, `startLine` and `totalLines`.
`image`	PNG, JPG/JPEG, GIF, WebP	Base64 image data, MIME type, original size and pixel dimensions. Presented visually to the model.
`pdf`	PDF files (supported models)	The PDF sent as a document block, plus file path and original size.
`parts`	Large PDFs / page extraction	Extracted page images and a page `count`.
`notebook`	`.ipynb` files	All cells with their outputs, combining code, text and visualizations.
`file_unchanged`	Repeat reads of the same range	A stub telling you the earlier read is still current (see below).

Text output format

Text content is returned in cat -n format, with line numbers starting at 1. For example:

     1  import { readFile } from 'fs/promises'
     2
     3  export function load(path) {
     4    return readFile(path, 'utf8')
     5  }

Images, PDFs and notebooks

Images (PNG, JPG, JPEG, GIF, WebP) are decoded and shown visually; Theus is multimodal. Large images are resized and compressed to fit the token budget automatically.
PDFs are read whole on supported models. For large PDFs (more than 10 pages) you must pass the pages parameter to read a specific range — reading a large PDF without pages fails. The maximum is 20 pages per request.
Notebooks (.ipynb) return every cell together with its outputs.

Page extraction for PDFs relies on poppler-utils. Install it with brew install poppler on macOS or apt-get install poppler-utils on Debian/Ubuntu.

Limits

Two caps apply to text reads:

Limit	Default	Checks	On overflow
Max file size	256 KB	Total file size	Errors before reading; use `offset`/`limit` for larger files.
Max output tokens	25000	Actual output tokens	Errors after reading; read a smaller portion or search instead.
Max lines per read	2000	Line count	Reads only the first 2000 lines unless `limit` is set.

You can raise the token cap with an environment variable:

THEUS_CODE_FILE_READ_MAX_OUTPUT_TOKENS=50000 ./bin/theus

Deduplication of repeat reads

If you read the exact same file and range again and the file hasn't changed on disk, the tool returns a file_unchanged stub instead of resending the whole content. The earlier read is still in context — refer to it rather than re-reading. This only applies to text and notebook reads (images and PDFs are not cached this way).

Errors and edge cases

Missing file: returns an error and, when possible, suggests a similar filename or a matching path under the current working directory.
Empty file: returns a system-reminder warning in place of content.
Offset past end of file: returns a warning noting the actual total line count.
Binary files: rejected, except images, PDFs and SVG which the tool renders natively.
Blocking device files (such as /dev/zero, /dev/random, /dev/stdin, /dev/tty): refused, since they would hang or produce infinite output.
Permission-denied paths: reads are checked against your permission settings; a path inside a denied directory is rejected.

When Theus reads a file it evaluates whether the content could be malware. Theus will analyze and explain suspicious code, but it will refuse to improve or augment code identified as malicious.

Related tools

Bash — for listing directories and other shell operations.
Glob / Grep — for finding files and searching content instead of reading whole files.
Edit / Write — for modifying files after reading them.

Theus — local-first multimodel coding agent · Made in Peru