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

Pi package that adds a `grep_ast` tool backed by [Aider-AI/grep-ast](https://github.com/Aider-AI/grep-ast).

`grep-ast` is **not** `ast-grep`: it searches by regular expression, then prints AST-aware structural context around matches (functions, methods, classes, loops, etc.) with line numbers. Use it when plain `grep` finds too little context and `ast-grep` is too structural for the task.

Based on code-archaeology use, `grep_ast` works best as a complement to plain grep rather than a complete replacement: use it first to discover entrypoints, classes/functions, dispatch points, and surrounding control flow; use plain grep for exhaustive literal audits such as status codes, exact response helpers, config keys, or all occurrences of one string.

## Install

```bash
pi install git:github.com/kafeg/pi-grep-ast
# or, after publishing to npm:
pi install npm:@kafeg/pi-grep-ast
```

The extension expects the Python CLI to be available as `grep-ast` or `gast`:

```bash
python -m pip install git+https://github.com/Aider-AI/grep-ast.git
```

## Tool

### `grep_ast`

Parameters:

- `pattern` — regular expression to search for
- `paths` — optional files/directories; defaults to `.` and respects `.gitignore`
- `ignoreCase` — optional `--ignore-case`
- `encoding` — optional file encoding
- `noGitignore` — optional; pass `--no-gitignore` to include ignored files
- `maxOutputChars` — optional truncation limit, default `20000`

The tool always passes `--line-number` so results can be cited as `file:line` references.

Example requests to Pi:

> Use grep_ast to find all uses of `fetchUser` in `src/` and show the surrounding functions/classes.

> Use grep_ast to find Python `requests.get` calls in `app/` and show the surrounding functions/classes.

> Use grep_ast to map likely HTTP route handlers and dispatch functions. Then use grep to enumerate exact status-code branches.

## Development

```bash
pi -e ./index.ts
```

For a quick CLI sanity check outside Pi:

```bash
grep-ast --no-color QTimer /path/to/repo/server
```