File tools

The file family covers reading content and applying changes. read opens almost anything through one path string; write creates or overwrites; edit applies scoped line edits through several variants; ast-edit performs structural rewrites.

read

Read files, directories, archives, SQLite databases, internal resources, images, documents, and URLs through a single path string. The trailing selector decides the slice.

Selectors

Line numbers are 1-indexed (:0 is invalid). URL selectors support only :raw, :N, :A-B, and :A+C — no L prefix.

What it can open

• Text files — when summarization is enabled and the file is small enough (<= 2 MiB, <= 20_000 lines), read returns a structural summary with elided spans replaced by ... plus a footer telling you the recovery selector; otherwise it streams a line-range read.
• Directories — a recency-sorted tree (depth 2, up to 12 children per directory) with sizes and ages.
• Archives — .tar, .tar.gz, .tgz, .zip via archive.ext:inner/path[:lines].
• SQLite — db.sqlite lists tables; :table shows schema + samples; :table:key reads a row; ?limit=&offset=&order=&where= queries; ?q=SELECT ... runs raw read-only SQL.
• Documents — .pdf, .doc(x), .ppt(x), .xls(x), .rtf, .epub are converted to text.
• Jupyter notebooks — .ipynb becomes editable # %% [code] cell:N text (unless :raw).
• Images — returns an inline image block (max 20 MiB), or metadata only when inspect_image.enabled.
• Internal URLs — agent://, artifact://, memory://, gjc://, rule://, issue://, pr://.
• Web URLs — http://, https://, or www.; rendered to reader-friendly text, with :raw for the body fallback.

write

Create or overwrite a file, archive entry, or SQLite row.

Variants:

• Plain file — overwrites existing files. Parent directories are created only on the archive path, not here.
• Archive entry — archive.ext:inner/path for .tar, .tar.gz, .tgz, .zip; the whole archive is rewritten after replacing one entry.
• SQLite insert — db.sqlite:table with a JSON5 object (empty object inserts default values).
• SQLite update/delete — db.sqlite:table:key; non-empty content updates, empty/whitespace content deletes.

edit

Apply source edits. The default mode is the hashline patch language, fed through one input string.

Hashline patch language

Anchors are the LINEhh token from read/search output (for example 41th). Copy only the part left of |. The parser checks the first and last anchor hashes against current file content; if they are stale it throws a mismatch and attempts cache-based recovery against the last read snapshot.

§src/a.ts
»4fb
const added = true;

§src/a.ts
≔4fb..6qx

Edit variants

The active mode is selected outside the tool payload by resolveEditMode() and the GJC_EDIT_VARIANT environment variable. The default is hashline.

ast-edit

Preview and apply structural rewrites over source files via native ast-grep.

It shares the ast-grep pattern grammar: $NAME captures a node, $_ matches one unbound, $$$NAME / $$$ match zero-or-more. Metavariable names must be uppercase and stand for whole nodes; captures from pat substitute into out.

File scope is capped by GJC_MAX_AST_FILES (default 1000). Directory scans honor .gitignore and skip node_modules unless the glob explicitly mentions it. Overlapping computed edits abort the run; files with syntax errors are skipped.

When to use which