name: ast-grep
description: "Use for compact code outlines, declarations, imports/exports, direct members, or syntax-aware pattern searches with ast-grep; not plain literal text search."
compatibility: "Requires ast-grep CLI; outline support varies by installed version."
ast-grep
Inspect syntax on demand; no index, LSP, rewrites, or semantic call-graph claims.
Before querying
Prefer normal text search for exact strings, comments, documentation, or filenames.
Check ast-grep --version and the needed subcommand's --help; installed help wins over newer web docs.
Missing binary/subcommand → report unavailable capability; use text search or source reads, without installing or upgrading.
Scope to candidate files/subdirectory first; retain default ignore/symlink boundaries.
Narrow noisy output before expanding scope; label truncated results as partial.
Outline first
Run from the target project's working directory; let ast-grep discover its project configuration normally.
Directory defaults show exports only; explicitly choose structure when internal declarations matter.
--match <regex> / --type <kind> filter top-level items, not members.
To locate a method, expand its containing declaration or use structural search.
Open only relevant source ranges after locating declarations.
Outlines describe extracted syntax, not every possible construct or runtime dependency.
Structural search
^ast-grep run --lang ts --pattern 'console.log($$$ARGS)' --color never src/
Single-quote patterns to preserve dollar signs.
$NAME matches one named AST node; $$$ARGS matches zero or more nodes.
Call-shaped patterns exclude comment/string lookalikes and tolerate formatting changes.
Match syntax in its actual grammar; do not treat patterns as regex or identifier matches as resolved references.
Unexpected zero hits → check scope, language, argument count, and pattern shape.
Test a minimal known-positive snippet through --stdin --lang <language>; add --debug-query=ast when needed.
Complex relational queries → consult current rule docs, rather than guessing traversal boundaries.
Stay read-only: no --rewrite, --update-all, or interactive edits under this skill.
Report evidence
Report each declaration or match with file:line evidence; prefer compact text, using --json=compact only for structured processing.
JSON positions are zero-based; add one when presenting human line numbers.
Inspect exit status and stderr: run uses 1 for no matches; outline can succeed with no selected entries.
Read/config/parser failures are not evidence of absence, even with exit 0.
In Nushell, inspect expected nonzero results with ^ast-grep ... | complete | to json so stdout, stderr, and exit_code remain visible.
Run error probes separately instead of hiding nested records or chaining commands that may stop early.
State scope and limitations; never promote syntactic imports or same-named calls into verified dependencies/callers.
---
name: ast-grep
description: "Use for compact code outlines, declarations, imports/exports, direct members, or syntax-aware pattern searches with ast-grep; not plain literal text search."
compatibility: "Requires ast-grep CLI; outline support varies by installed version."
---
# ast-grep
Inspect syntax on demand; no index, LSP, rewrites, or semantic call-graph claims.
## Before querying
- Prefer normal text search for exact strings, comments, documentation, or filenames.
- Check `ast-grep --version` and the needed subcommand's `--help`; installed help wins over newer web docs.
- Missing binary/subcommand → report unavailable capability; use text search or source reads, without installing or upgrading.
- Scope to candidate files/subdirectory first; retain default ignore/symlink boundaries.
Narrow noisy output before expanding scope; label truncated results as partial.
## Outline first
Run from the target project's working directory; let ast-grep discover its project configuration normally.
```nu
^ast-grep outline --items structure --view names src/
^ast-grep outline --items structure --view expanded src/client.ts
^ast-grep outline --items imports --view signatures src/client.ts
^ast-grep outline --items exports --view signatures src/
```
- Directory defaults show exports only; explicitly choose `structure` when internal declarations matter.
- `--match <regex>` / `--type <kind>` filter top-level items, not members.
To locate a method, expand its containing declaration or use structural search.
- Open only relevant source ranges after locating declarations.
Outlines describe extracted syntax, not every possible construct or runtime dependency.
## Structural search
```nu
^ast-grep run --lang ts --pattern 'console.log($$$ARGS)' --color never src/
```
- Single-quote patterns to preserve dollar signs.
`$NAME` matches one named AST node; `$$$ARGS` matches zero or more nodes.
Call-shaped patterns exclude comment/string lookalikes and tolerate formatting changes.
- Match syntax in its actual grammar; do not treat patterns as regex or identifier matches as resolved references.
- Unexpected zero hits → check scope, language, argument count, and pattern shape.
Test a minimal known-positive snippet through `--stdin --lang <language>`; add `--debug-query=ast` when needed.
- Complex relational queries → consult current [rule docs](https://ast-grep.github.io/guide/rule-config/relational-rule.html), rather than guessing traversal boundaries.
- Stay read-only: no `--rewrite`, `--update-all`, or interactive edits under this skill.
## Report evidence
- Report each declaration or match with file:line evidence; prefer compact text, using `--json=compact` only for structured processing.
JSON positions are zero-based; add one when presenting human line numbers.
- Inspect exit status and stderr: `run` uses 1 for no matches; `outline` can succeed with no selected entries.
Read/config/parser failures are not evidence of absence, even with exit 0.
In Nushell, inspect expected nonzero results with `^ast-grep ... | complete | to json` so `stdout`, `stderr`, and `exit_code` remain visible.
Run error probes separately instead of hiding nested records or chaining commands that may stop early.
- State scope and limitations; never promote syntactic imports or same-named calls into verified dependencies/callers.
## Sources
- [Outline CLI](https://ast-grep.github.io/reference/cli/outline.html)
- [Search CLI](https://ast-grep.github.io/reference/cli/run.html)
- [Pattern syntax](https://ast-grep.github.io/guide/pattern-syntax.html)