Introducing ast-grep Outline | ast-grep

Skip to content

Appearance

MenuReturn to top

Introducing ast-grep Outline ​<br>ast-grep outline is released in ast-grep 0.44.0 as an alpha preview, and feedback is welcome.

Code agents are getting better at editing projects, but they still spend a lot of time opening files just to learn what is inside. Before changing code, an agent often needs a quick map of a file's exports, imports, classes, structs, and methods. Reading the whole file works, but it is expensive in tokens and slow in large repositories.<br>ast-grep outline is a new command designed for that first pass.<br>sh# Summarize one file before opening the full source.<br>ast-grep outline src/parser.ts<br># List the exported surface of a directory.<br>ast-grep outline src<br># Focus on one symbol and expand its local details.<br>ast-grep outline src/parser.ts --match Parser --view expanded<br>It parses source files with ast-grep rule and tree-sitter, then prints a compact table of contents: functions, classes, structs, imports, exports, direct members, and source ranges. It is not a language server or semantic graph, just a small structural primitive for deciding what to read next.

In the validated benchmark run, outline cut median Claude Code cost by 35% on VS Code, 55% on Django, and 40% on OkHttp while keeping median baseline coverage and precision at 100%. The detailed numbers and caveats are below, but the short version is simple: on larger repositories, a structural first pass can replace a lot of broad file reading .<br>Why Outline? ​<br>The most common code-navigation loop is not "answer every question about this repository." It is much smaller:<br>Find the file that probably matters.<br>Understand the file's shape.<br>Open the smallest useful source range.<br>Repeat with better context.<br>Traditional grep is excellent for step one. Read or an editor is necessary for step three. The missing piece is step two: a cheap summary of source structure after you have a candidate file or directory.<br>ast-grep outline fills that gap with two defaults tuned for navigation.<br>Inspect a file's local shape when you already have a likely source file before reading the implementation:<br>console$ ast-grep outline src/parser.ts<br>src/parser.ts<br>12: export function parseRule(source: string)<br>40: export class Parser<br>fields: source, diagnostics<br>methods: parse, recover, finish<br>Inspect a folder's exported surface when you are scanning a subtree. Directory outlines default to exports:<br>console$ ast-grep outline src<br>src/parser.ts<br>12: export function parseRule(source: string)<br>40: export class Parser<br>src/rule.ts<br>8: export interface Rule<br>21: export function validateRule(rule: Rule)<br>After the first outline, you can narrow the same structural view to dependencies, a single symbol, or matching imports without falling back to full-file reads.<br>File ImportsExpand SymbolFolder Imports<br>console# Check what one file depends on.<br>$ ast-grep outline src/parser.ts --items imports<br>src/parser.ts<br>3: import { Rule } from "./rule"<br>4: import { Scanner } from "./scanner"<br>console# Expand a known top-level symbol without reading its full body.<br>$ ast-grep outline src/parser.ts --match Parser --type class --view expanded<br>src/parser.ts<br>40: export class Parser<br>42: source: string<br>43: diagnostics: Diagnostic[]<br>45: parse(): Rule<br>58: recover(error: ParseError): void<br>66: finish(): ParseResult<br>console# Find imports matching one dependency across a folder.<br>$ ast-grep outline src --items imports --match ast-grep-core --view signatures<br>src/parser.ts<br>6: import { parseAst } from "ast-grep-core"<br>src/checker.ts<br>11: import { Rule } from "ast-grep-core"

Machine-readable output is planned as part of the upcoming release work.<br>For coding agents, this makes outline a cheaper first read when the question is about shape rather than implementation. It gives precise file and range metadata, so an agent can move from a directory summary to a symbol and then to a small source slice. That is where the token savings come from.<br>Benchmark Result ​<br>In the validated benchmark run, outline kept median baseline coverage and precision at 100% across all seven repositories while usually reducing cost on larger repositories. Exact paired-run alignment still varied: VS Code matched exactly in 3/4 paired runs, and Excalidraw in 2/4. Those misses are shown in the folded table rather than hidden.<br>VS Code, Django, and OkHttp were the clearest wins, with median cost reduced by 35%, 55%, and 40%. Smaller repositories such as Gin and Alamofire were already cheap to explore with grep and direct reads, so outline sometimes added work instead of saving it.<br>The result is not "outline always reduces tool calls." It helps most when it replaces broad file reads with compact structure. Agents still need judgment about when a grep result is enough and when a structural summary will save the next few reads.

Benchmark setup and performance tableSetup ​<br>I tested outline with headless Claude Code on real architecture questions. Each scenario ran twice:...