@mammothb/pi-read

Smart read for pi — returns an AST structural outline for large files, and delegates everything else to the built-in read.

Behavior

Input	Result
Small file (≤ threshold)	Built-in read (full content, exact output)
Large file, supported + enabled language	AST outline with line ranges
Large file, unsupported/disabled language	Built-in read (truncate + "continue" markers)
Image / binary	Built-in read (image attachment, MIME handling)
offset/limit drill-down	Built-in read (raw section)
Missing path / directory	Built-in read

The override spreads createReadToolDefinition and only replaces execute, so fallback paths are byte-identical to the built-in read — truncation signaling, image attachments, prompt metadata, and TUI rendering all preserved.

Optional dependencies

tree-sitter is fully optional and WASM-based (no native build):

• web-tree-sitter — the WASM runtime (Parser.init(), Language.load()).
• grammar packages — each ships a prebuilt .wasm (e.g. tree-sitter-python/tree-sitter-python.wasm).

When any is missing, large files fall through to the built-in read.

Config

.pi/pi-read.json (project) over ~/.pi/agent/pi-read.json (global):

{
  "enabled": true,
  "thresholdLines": 2000,
  "thresholdBytes": 51200,
  "maxBytes": 10485760,
  "maxDepth": 10,
  "languages": {
    "typescript": true,
    "tsx": true,
    "javascript": true,
    "csharp": true,
    "python": true,
    "rust": true
  }
}

Set a language to false to disable outlining for it (falls back to built-in read).

Supported languages

Language	Extensions	Symbols
TypeScript / TSX	.ts, .mts, .cts, .tsx	class, function, method, interface, enum, type alias, arrow-fn const
JavaScript	.js, .mjs, .cjs, .jsx	class, function, method, interface, enum, type alias, arrow-fn const
C#	.cs	class, interface, method, constructor, struct, enum, namespace
Python	.py	class, function
Rust	.rs	function, struct, enum, trait, impl

Symbols render as a terse outline with line ranges:

server.ts (typescript) — 2502 lines
├── class App (3 children) [1:7]
│   ├── method constructor [2:2]
│   └── method handleRequest [3:5]
└── function main [8:10]

Use read with offset/limit to view a specific section.