| name | ast-grep-outline |
| description | Use when exploring or modifying a codebase and you need a cheap structural map of files, directories, imports, exports, or direct members before reading full source. |
Use ast-grep outline
ast-grep outline prints a compact structural map of source code with line
numbers: top-level items (imports, functions, classes, structs,
interfaces, modules, enums) and their direct members (fields, methods,
constructors, enum variants). It is a local, syntax-only view — cheap enough
to run before any full file read.
Read code in stages: find candidate files with search or file names, outline
them, then open only the source range the outline points to. Defaults adapt to
input: a file shows its local structure with member digests; a directory shows
only its exported surface as grouped names.
When To Use It
Understand a file before editing. Get a table of contents, dependencies,
and public entry points before reading implementation details:
ast-grep outline <file>
ast-grep outline <file> --items imports
ast-grep outline <file> --items exports
Map an unfamiliar directory. Scan the public surface of a subtree, then
narrow by symbol type when you know what you are looking for:
ast-grep outline <dir> --items exports
ast-grep outline <dir> --type struct,enum,function
Zoom into a known symbol. After search finds a likely name, list its
members with line numbers instead of reading the whole body:
ast-grep outline <file> --match <symbol> --type class --view expanded
Trace dependency direction. Find which files import a package or module to
decide where a change belongs:
ast-grep outline <dir> --items imports --view signatures
Review changed files after editing. Git tells you what changed; outline
summarizes the resulting structure and public surface:
ast-grep outline $(git diff --name-only HEAD) --items exports
Argument Guide
--items <KIND> selects top-level items: structure for local declarations
(file default), exports for public API (directory default), imports for
dependencies, all when import/export edges matter together.--view <VIEW> controls detail, from least to most: names for directory
scans, signatures for one line per item, digest for signatures plus
member names, expanded for one line per member with its line number.--match <REGEX> filters top-level items by name or signature. Rust regex,
case-sensitive; it never matches members.--type <TYPE[,TYPE...]> keeps only some top-level symbol types, such as
--type class,function. Member types like method,field never match
top-level items.--pub-members hides private members when the view prints members.--json=stream emits one JSON object per file with precise ranges. Use it
only to pipe or post-process entries; prefer text for navigation.
Limits
outline shows local syntax structure. It does not resolve references, infer
types, follow re-export chains, or build a call graph. Use ast-grep run,
rg, or compiler-backed tools for those questions, then outline the candidate
files they surface.
## NodeTool notes
Vendored from https://github.com/ast-grep/agent-skill @ c2a9bc1 (2026-07-03).
Run via `npx --yes --package @ast-grep/cli ast-grep outline <args>` (bare
`npx @ast-grep/cli` fails — the binary is named `ast-grep`).
