| name | ast-outline |
| description | Tree-sitter-based CLI for code exploration — outlines, digests, symbol extraction, and AST-aware grep. Prefer over full file reads for structure.
|
ast-outline
ast-outline is the primary code-structure tool. It replaces full file reads with compact
tree-sitter-based structural output for supported languages. Use it before opening full
file contents.
Available tools
| Tool | Purpose |
|---|
ast-outline <paths…> | Default: signatures + line ranges, no bodies |
ast-outline digest <paths…> | One-page module map with size labels |
ast-outline show <file> <Symbol…> | Extract one or more symbol bodies |
ast-outline grep <pattern> <paths…> | AST-aware structural search (grouped by scope) |
ast-outline prompt | Print the canonical agent snippet for context files |
Broad-to-narrow workflow
Start broad, drill only when needed:
-
Unfamiliar directory — ast-outline digest src/: one-page map of types and methods.
Each file tagged [tiny] / [medium] / [large] / [huge]. [huge] files
(≥100k tokens) collapse to header-only; call ast-outline outline <path> to expand.
-
File-level shape — ast-outline src/foo.ts: signatures with line ranges, 2-10x
smaller than full read. A # WARNING: N parse errors means the outline is partial.
-
One symbol — ast-outline show foo.ts MyClass: extract just one type/method body.
Suffix matching: User for the type, TakeDamage for one method, Player.TakeDamage
when ambiguous. Multiple at once: ast-outline show foo.ts TakeDamage Heal Die.
Add --signature for header only (docs + attrs + signature, no body).
-
Where a symbol appears — ast-outline grep User.save src/: matches grouped by
enclosing scope, tagged [def] / [import]. Batch with -e:
ast-outline grep User.save -e User.load src/. Narrow with --kind def|call|ref|import.
Key features
- Multiple paths in one call —
outline and digest accept mixed file/directory args
--imports — shows import/use/using statements verbatim in native syntax--exclude <glob> — skip test trees, generated files (--exclude tests/ --exclude '*.gen.*')- Language support —
.cs, .cpp/.cc/.h, .py, .ts/.tsx, .js/.jsx, .java,
.kt, .scala, .go, .rs, .php, .rb, .ex/.exs, .lua, .gd, .swift,
.css/.scss, .sql, .html, .htm, .vue, .md, .yaml/.yml
- Cross-language inheritance — type headers carry
: Base, Trait in signatures
- Batch grep — repeatable
-e flag for multi-pattern search in one tree walk
Fallback
Fall back to native Read / Grep / Glob when ast-outline is unavailable
(command not found), or when dealing with unsupported file formats.
Reference
Run ast-outline help for all flags and commands.
