OpenParable
Skip to content
← Back to skills

Ast Grep Outline

Development
ast-grep-outline

Ast Grep Outline is an Agent Skill for development published in the ast-grep/agent-skill repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/ast-grep/agent-skill/blob/HEAD/ast-grep/skills/outline/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/ast-grep-outline, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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.