mcpField
A
ast-grep-outline

ast-grep-outline

github.com/ast-grepDevelopment8992.5k installsUpdated 7w ago
Repository

About ast-grep-outline

A skill for using ast-grep outline to create compact structural maps of source code. It helps developers inspect declarations, members, and line numbers before opening relevant code; it shows local syntax without resolving references or building call graphs.

Key features

  1. 01List top-level declarations and members
  2. 02Show line numbers and signatures
  3. 03Filter by exports, imports, or structure
  4. 04Filter items by name or type
  5. 05Emit file structure as a JSON stream

Use cases

  1. 01Review a file structure before editing
  2. 02Map the public API of an unfamiliar directory
  3. 03Find a symbol's members and line numbers
  4. 04Trace dependency direction between files
  5. 05Review structure in changed files

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/ast-grep/agent-skill --skill ast-grep-outline

After installing, type/ast-grep-outlinein Claude Code to confirm it loaded.

Details

From the project README

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.

Comments

Markdown supported