@yusukeshib/pi-ast-read

A pi extension for semantic, token-cheap reading of large source files. Instead of reading a whole file into context, outline its symbols first, then pull only the one you need.

It adds two tools (it does not override the built-in read, so it coexists with pi-token-counter and any other read-wrapping extension):

Tool	Returns
ast_read_tree({ path })	the file's symbol outline — signatures + line ranges, nested, no bodies
ast_read_symbol({ path, symbol })	just that symbol's source (the matched node's lines, with line numbers)

Typical workflow: call ast_read_tree to see the shape of a big file, then ast_read_symbol (or read with offset/limit) to pull only the part you need.

Supported languages

Backed by ast-grep (tree-sitter):

• Rust
• TypeScript / TSX
• JavaScript / JSX
• Python
• Shell (bash / sh)
• Makefiles (small built-in parser — ast-grep has no make grammar)

Files in other languages return a clear error so the caller falls back to the built-in read.

The read nudge

The extension also installs a tool_call nudge: when the agent tries to read a supported-language file whole (no offset/limit) and the file is large, the read is blocked once with a reason pointing at ast_read_tree. The hook only observes the event bus (it does not own the read tool), so it coexists with other read-wrapping extensions. It is deliberately silent on unsupported languages — suggesting ast_read_tree for a .go/.json/.md file would be a dead end.

Tunables:

Env var	Default	Meaning
AST_READ_NUDGE_BYTES	20000	Minimum file size (bytes) to nudge
AST_READ_NUDGE	1	Set to 0 to disable the nudge

Requirements

ast-grep must be on your PATH:

nixy install ast-grep   # or: brew install ast-grep

Install

pi install npm:@yusukeshib/pi-ast-read

Via git (no npm publish required):

pi install git:github.com/yusukeshib/pi-ast-read

Try it without installing:

pi -e npm:@yusukeshib/pi-ast-read

License

MIT