read_file

The single door. It shows a project as folders and files and a file as named parts, lets the agent change exactly one part at a time, and never saves a change that breaks syntax or configuration.

Components

How it works

read_file() lists your projects; a project name shows its structure, with coordinates and no code; a coordinate opens a file's map or one segment. read_file parses a file into named segments: functions, classes, configuration blocks, paragraphs. The file map is one line per segment, with classes listing their methods. 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

• projects: read_file() with no path lists them.
• structure: a project name or a folder: folders and files with coordinates. Above about 3,000 tokens it gives an overview per folder and asks for a search.
• file map: the default view of a file, one line per segment. The same 3,000-token rule applies; full_skeleton forces the whole map.
• search: file and folder names in a project, segment names in a file.
• segment: one part by address, such as 5.3, or straight from the project by coordinate, such as d.a.f.31.17.
• trace: on a file, what it imports, who imports it, the databases, programs and servers it touches, and any import that leads nowhere right now; direct neighbours not yet verified get a level 3 check, stopping at the first failure. On a project, its data flow.
• status: lists open edit buffers.

Editing

• One edit at a time: each change is saved, undone or discarded before the next.
• 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 save is checked again, so an undo never slips past the checks.

Safety

• Read before write: a segment must have been displayed since the last change before it can be changed.
• Checked saves, level 1: syntax, with the language's own checker where there is one. A failure is not saved, and the error names the line.
• Level 2: configuration files through their service's checker, such as nginx -t, systemd-analyze verify or sshd -t. A failure is not saved; linter findings are only reported.
• Level 3: connections. Imports must lead to a project file or an installed package (for Python, in the project's venv), and SQL must match the live database schema. A gap is saved and listed, so the first files of a project can import files that do not exist yet.
• Level 3 checks the code being saved, not an older index, and every save re-indexes the file.
• diff shows changes against disk; discard drops the edit buffer.
• save (commit): an atomic write, after the checks. 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.
• Checked saves turn a broken edit into a clear error message with a line number instead of a broken file.
• In typical use the agent reads about 120 lines instead of a whole 5,000-line file.