ast-grep-outline
ast-grep/agent-skill
Get a structural map of code files and directories with line numbers—imports, exports, functions, classes, and their members.
What is ast-grep-outline?
ast-grep outline prints a compact syntax-based view of top-level items (functions, classes, imports, exports) and their direct members with line numbers. Use it to explore unfamiliar code, find entry points, and understand dependencies before reading full source files.
- Print top-level declarations (imports, functions, classes, structs, interfaces, modules, enums) with line numbers
- Show direct members (fields, methods, constructors, enum variants) of each item
- Filter by item kind (structure, exports, imports, all) and symbol type (class, function, struct, enum, etc.)
- Display varying detail levels from names-only to expanded member lists with line ranges
- Scan directories to show only exported surface as grouped names
- Process multiple files at once, including git-changed files
How to install ast-grep-outline
npx skills add https://github.com/ast-grep/agent-skill --skill ast-grep-outlineHow to use ast-grep-outline
- 1.Run `ast-grep outline <file>` to see a file's local structure with imports, exports, and members
- 2.Use `--items imports` or `--items exports` to filter to dependencies or public API only
- 3.Add `--type class,function` to keep only specific symbol types
- 4.Use `--match <regex>` to filter top-level items by name
- 5.Add `--view expanded` to see one line per member with its line number
- 6.Run on multiple files or git-changed files: `ast-grep outline $(git diff --name-only HEAD)`
Use cases
- Understand a file's structure and public API before editing it
- Map an unfamiliar directory to find relevant modules and entry points
- Locate a known symbol and list its members instead of reading the whole body
- Trace which files import a package to decide where a change belongs
- Review the resulting structure after editing multiple files
- Code explorers and refactorers navigating unfamiliar codebases
- Developers making targeted edits who need quick context before diving into source
- Teams reviewing changes to understand structural impact
- Anyone using ast-grep for syntax-based code search and analysis
ast-grep-outline FAQ
No. It shows local syntax structure only—no type inference, reference resolution, or re-export chains. Use ast-grep run, rg, or compiler tools for those questions, then outline the candidate files they surface.
Files show local structure with member digests; directories show only exported surface as grouped names by default.
Yes, use `--json=stream` to emit one JSON object per file with precise ranges. Prefer text output for navigation.
Start with `names` for directory scans, `signatures` for one line per item, `digest` for signatures plus member names, or `expanded` for one line per member with line numbers.
Add the `--pub-members` flag to show only public members when the view prints members.
Full instructions (SKILL.md)
Source of truth, from ast-grep/agent-skill.
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:structurefor local declarations (file default),exportsfor public API (directory default),importsfor dependencies,allwhen import/export edges matter together.--view <VIEW>controls detail, from least to most:namesfor directory scans,signaturesfor one line per item,digestfor signatures plus member names,expandedfor 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 likemethod,fieldnever match top-level items.--pub-membershides private members when the view prints members.--json=streamemits 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.
Related skills
More from ast-grep/agent-skill and the wider catalog.



