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).