read_file

The segment editor. It shows a file as named parts, lets the agent change exactly one of them and refuses to save anything that does not pass verification.

Components

How it works

read_file parses a file into named segments: functions, classes, configuration blocks, paragraphs. By default it returns the skeleton, the list of segments with their names and sizes, not the code. The agent reads only the segment it needs. Every byte of the file belongs to exactly one segment, including blank lines, so joining the segments always gives back the original file.

Capabilities

Reading

• skeleton: the default view; full_skeleton forces the whole map of a very large file.
• search: narrows a large skeleton to matching segments.
• segment: reads one part by address, such as 5.3.
• trace: follows the file's signal through the codebase: what it imports, who imports it, and the databases, programs and servers it touches. It then checks the direct neighbours: any that has not been verified gets a level 3 check, and the walk stops at the first failure.
• status: lists open edit buffers.

Editing

• replace, insert between two segments, delete, move.
• comment_out and uncomment a segment while debugging.
• paste: copy a segment, or a whole file, verbatim from the read buffer into the file being edited (see the clipboard below).

Two buffers and the clipboard

read_file keeps exactly two buffers per sandbox. The read buffer is read-only and always fresh, and doubles as a clipboard: open any file there, then paste one of its segments, or the whole file, verbatim into a segment of the file you are editing. The model never retypes code it copies, so nothing is lost or changed on the way, and it costs almost no tokens. The edit buffer holds the one file being changed; it is committed or discarded before another file is opened for editing.

Undo

• Every edit records its inverse: the previous text, a deleted segment with its position and children, or where a moved segment used to be. The record is also written to the edit history database.
• undo reverts the last edit.
• undo with an address reverts the latest change to that one segment, even when other edits came after it.
• undo all reverts every edit since the last commit.
• Inserts, deletes and moves change the structure of the file, so they are undone in reverse order (last in, first out). Text replacements can be undone in any order.
• Every undo clears the verification: the file must pass verify again before it can be committed.

Safety

• Read before write: a segment must have been displayed since the last change before it can be changed.
• verify: level 1 syntax; level 2 the language's compiler or the service's own checker, such as nginx -t, systemd-analyze verify or sshd -t; level 3 imports and external references must resolve.
• diff shows changes against disk; discard drops the edit buffer.
• commit: an atomic write, only with a current verification. It writes through symlinks to the real file and keeps its permissions.

Languages

16 tree-sitter grammars: Python, JavaScript, TypeScript, HTML, CSS, Go, Rust, C, C++, Java, C#, PHP, Ruby, Bash, Swift and Kotlin. Configuration files (nginx, systemd units, sshd_config, INI and more) get structure-aware segments, and plain text and Markdown are split into paragraphs.

Why it is built this way

• Segments instead of lines: a function named authenticate_user stays addressable when it moves from line 214 to line 389.
• Read before write stops the most common agent mistake: editing code it never looked at.
• Verify before commit turns a broken edit into a clear error message instead of a broken file.
• In typical use the agent reads about 120 lines instead of a whole 5,000-line file.