---
slug: "yusukeshib-pi-ast-read"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/yusukeshib/pi-ast-read@main/README.md"
repo: "https://github.com/yusukeshib/pi-ast-read"
source_file: "README.md"
branch: "main"
---
# @yusukeshib/pi-ast-read

A [pi](https://pi.dev) 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](https://github.com/yusukeshib/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`](https://ast-grep.github.io/) (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`:

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

## Install

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

Via git (no npm publish required):

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

Try it without installing:

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

## License

MIT