pi-tree-sitter

Pre-write syntax validation and structural code tools for pi using tree-sitter WASM grammars.

Write-time validation: hooks into write and edit tools to parse content before it hits disk. If tree-sitter finds syntax errors, the extension blocks the tool with actionable feedback — line, column, source snippet, and for MISSING nodes, what token was expected. The LLM sees the error in the same turn and self-corrects.

Semantic code tools: registers list_symbols, find_definition, find_callers, find_callees, and get_symbol_body tools so the agent can query code structure — functions, classes, methods, interfaces — without grepping or reading whole files.

Inspired by dirge's syntax_validator.rs and semantic adapters.

Installation

pi install npm:pi-tree-sitter

Git version

pi install git:github.com/markokocic/pi-tree-sitter

Or clone and use locally:

git clone https://github.com/markokocic/pi-tree-sitter.git
cd pi-tree-sitter
npm install
pi install .

Run ad-hoc without installing:

pi -e ./path/to/pi-tree-sitter

Tools

| Tool | Parameters | Description | |------|-----------|-------------| | list_symbols | path?, kind? | List symbols (functions, classes, methods, etc.) in a file or across the project. Parses code with tree-sitter for accurate results. Use this instead of grep when looking for code structure. | | find_definition | name | Find where a SYMBOL (function, class, type, etc.) is DEFINED across the project. Uses tree-sitter for precise structural matching. NOT for finding files by name — use find_files for that. NOT for content search — use grep. | | find_callers | name, path? | Find all call sites of a function or method across the project, with file path and line number. Excludes the definition site. | | find_callees | path, name | Find all functions/methods called by a given symbol, with line number per call site. | | get_symbol_body | path, name | Get the full source code of a named symbol (function, class, method, etc.) from a file. Uses tree-sitter to precisely extract by byte range. |

All tools parse code with tree-sitter on demand — no caching, always fresh.

TUI Rendering

All symbol tools include custom renderCall and renderResult for a polished terminal experience:

• Tool title shows the tool name and its parameters inline: find_definition — myFunction list_symbols src/file.ts [kind: function]
• Collapsed (default — press Ctrl+O to expand): compact summary: ✓ 42 symbols across 5 files ✓ 3 definitions for 'myFunction'
• Expanded (Ctrl+O): full detail output
• get_symbol_body renders expanded source with syntax highlighting via highlightCode(), auto-detecting the language from the file extension

Write-time validation

The extension hooks write and edit tools. Before content hits disk, it's parsed with the matching tree-sitter grammar. If ERROR or MISSING nodes are found (capped at 10), the tool is blocked with:

Syntax check failed for src/main.rs: 2 error(s) detected by tree-sitter.
Fix and re-submit. (This is a pre-write guard — the file was NOT modified.)
  missing `}` at 42:1: fn main() {
  syntax error at 15:8: let x =

For edit tools, the extension runs the edit tool's own execution in memory (file operations redirected) and validates the result — so the guard always checks exactly what the tool would write. If an oldText matched only a prefix of a line — leaving trailing characters behind after the replacement, a common cause of rejected edits — the block message names that edit and line instead of only showing the resulting syntax error. Edits the edit tool itself would reject with a precise error (text not found, non-unique, overlapping) are left for the tool to report. For languages without WASM grammars, a comment/string-aware delimiter-balance scanner provides fallback validation.

Languages

WASM grammars + symbol tools (21 configs)

| Language | Extensions | Symbols | |----------|-----------|---------| | TypeScript / JavaScript | .ts, .tsx, .mts, .cts, .js, .jsx, .mjs, .cjs | functions, classes, interfaces, types, methods, variables | | Python | .py, .pyi | functions, classes, methods, decorated definitions | | Rust | .rs | functions, structs, enums, traits, impl methods | | Go | .go | functions, methods, structs, interfaces | | Java | .java | classes, interfaces, enums | | C# | .cs | classes, structs, interfaces, enums, methods, namespaces | | Kotlin | .kt, .kts | functions, classes, interfaces, objects, properties | | Ruby | .rb | methods, classes, modules | | PHP | .php | functions, classes, interfaces, traits, methods | | Dart | .dart | functions, classes, mixins, enums, methods, variables | | C | .c, .h | functions, structs, unions, enums | | C++ | .cpp, .cc, .cxx, .hpp, .hh, .hxx | functions, classes, structs, namespaces | | Bash | .sh, .bash | functions | | Clojure / EDN / Babashka / ClojureDart | .clj, .cljs, .cljc, .cljd, .edn, .bb | functions, vars, protocols, records | | Elixir | .ex, .exs | functions, modules, protocols | | Scala | .scala | functions, classes, traits, objects | | Swift | .swift | functions, classes, structs, protocols, enums | | Lua | .lua | functions | | Zig | .zig | functions, variables, containers | | Scheme | .scm, .ss | validation only | | Racket | .rkt | validation only |

WASM validation only (no symbol tools)

| Language | Extensions | |----------|-----------| | Haskell | .hs, .lhs | | CSS | .css | | HTML | .htm, .html | | JSON | .json | | TOML | .toml | | YAML | .yaml, .yml | | Vue | .vue |

Delimiter balance only (no WASM grammar available)

| Language | Extensions | |----------|-----------| | Common Lisp | .lisp, .lsp, .cl | | Emacs Lisp | .el | | Fennel | .fnl | | Janet | .janet, .jdn |

Grammar caching

WASM grammars are fetched from jsDelivr CDN and cached to ~/.cache/pi-tree-sitter/. Each grammar has three files:

• <wasm> — the WASM binary
• <wasm>.etag — server ETag for conditional requests
• <wasm>.date — last-checked timestamp

On every load, the .date file is checked. Only if 30+ days old does the extension revalidate against the CDN using If-None-Match with the stored ETag:

• 304 Not Modified → touches .date (zero bytes transferred, timer reset)
• 200 OK → downloads updated grammar, saves new WASM + ETag + date
• Network error → keeps cache, touches .date (retries in 30 days)

On first download, the bytes are verified with Language.load() before persisting. If cached bytes are ever corrupted, they are deleted and re-downloaded on the next access.

How it works

1. Write-time validation hooks tool_call events for write and edit
2. Semantic tools are registered via pi.registerTool() with TypeBox parameter schemas
3. Each tool parses the relevant file(s) with tree-sitter on demand (no in-memory cache)
4. Per-language extractors map grammar-specific node types to a unified Symbol kind
5. Callee queries use tree-sitter S-expression queries for each language

Project structure

pi-tree-sitter/
  index.ts           # Extension entry: write/edit hooks + 5 tool registrations
  src/
    grammar.ts       # LANGUAGE_MAP, WASM loading from CDN, disk cache with ETag
    delimiter.ts     # Comment/string-aware delimiter balance scanner (fallback)
    edit-guard.ts    # In-memory edit simulation via the tool's own execute + prefix-match diagnosis
    languages.ts     # 21 per-language configs: extractors + callee queries
    files.ts         # Recursive project file discovery

License

EPL-2.0 — Copyright 2026 Marko Kocic