ast-outline

Fast, AST-based structural outline for source files — classes, methods, signatures with line numbers, but no method bodies. Built for LLM coding agents and humans who want to read the shape of a file before diving into the whole thing.

ast-outline is written in Rust, leveraging the incredibly fast ast-grep bindings for tree-sitter, and it utilizes rayon to parse your entire workspace concurrently in milliseconds.

---

Purpose

ast-outline exists to make LLM coding agents faster, cheaper, and smarter when navigating unfamiliar code.

Modern agentic coding tools explore codebases by reading files directly — not via embeddings or vector search. That approach is reliable but has a massive cost: on a 1000-line file, the agent pays for 1000 lines of tokens just to answer "what methods exist here?".

ast-outline closes that gap. It's a pre-reading layer:

1. Token savings — typically 5–10×. An outline replaces a full file read when you only need structural understanding.
2. Faster exploration. A whole module's public API fits on one screen.
3. Precise navigation. Every declaration has a line range (L42-58). You go straight to the method body you need.
4. AST accuracy, not fuzzy match. implements and show understand real syntax — no false positives from comments or strings like grep.
5. Zero infrastructure. No index, no cache, no embeddings, no network. Live, always fresh, invisible to your repo.

The workflow

Before ast-outline:

Agent: Read Player.cs            # 1200 lines of tokens
Agent: Read Enemy.cs             # 800 lines of tokens
Agent: Read DamageSystem.cs      # 400 lines of tokens
Agent: grep "IDamageable" src/   # noisy, lots of false matches
...

With ast-outline:

Agent: ast-outline digest src/Combat         # ~100 lines, whole module
Agent: ast-outline implements IDamageable    # precise list, no grep noise
Agent: ast-outline show Player.cs TakeDamage # just the method body

Result: same understanding, a fraction of the tokens, a fraction of the round-trips.

---

Supported languages

Language	Extensions
Rust	.rs
C#	.cs
Python	.py, .pyi
TypeScript	.ts, .tsx
JavaScript	.js, .jsx, .mjs, .cjs
Java	.java
Kotlin	.kt, .kts
Scala	.scala, .sc
Go	.go
Markdown	.md, .markdown, .mdx, .mdown

More coming soon! Adding another language is a single new adapter file leveraging the massive ast-grep language ecosystem.

---

Install

Homebrew (macOS)

brew install aeroxy/ast-outline/ast-outline

Cargo

cargo install ast-outline

This installs the ast-outline CLI globally into ~/.cargo/bin — make sure that's on your PATH.

---

Quick start

# Structural outline of one file
ast-outline path/to/Player.rs
ast-outline path/to/user_service.py

# Outline a whole directory (recurses supported extensions in parallel)
ast-outline src/

# Print the exact source of one specific method
ast-outline show Player.cs TakeDamage

# Compact public-API map of a whole module
ast-outline digest src/Services

# Every class that inherits/implements a given type
ast-outline implements IDamageable src/

# Output a prompt snippet to steer LLM agents
ast-outline prompt >> AGENTS.md

---

Using with LLM coding agents

This is the main use case. Add the snippet below to your CLAUDE.md, AGENTS.md, subagent file, or any system prompt that steers a coding agent. It will then prefer ast-outline over reading full files.

The snippet ships with the tool — ast-outline prompt prints it verbatim, so you can append it to a project's agent config without copy-pasting:

ast-outline prompt >> AGENTS.md
ast-outline prompt >> .claude/CLAUDE.md
ast-outline prompt | pbcopy   # macOS clipboard

Works with

• Claude Code (+ custom subagents like Explore, codebase-scout)
• Cursor agent mode
• Aider
• Copilot Chat / Workspace
• Any custom agent on the Claude / OpenAI / Gemini APIs
• Humans (the colored terminal format is highly readable; show is a nice alternative to grep -A 20)

---

Output format

The format is designed to be LLM-friendly: Python-style indentation, line-number suffixes in L<start>-<end> form, doc-comments preserved. The header summarises scale and flags partial parses.

When you run it yourself, you'll see a gorgeous ANSI-colored output. Don't worry, the terminal colors are automatically stripped when piped to a file or consumed by an agent's shell hook!

Rust

# src/core.rs (490 lines, 3 types, 12 methods, 5 fields)
pub struct Declaration  L10-120
    pub kind: DeclarationKind  L12
    pub name: String  L15
    pub fn lines_suffix(&self) -> String  L30-48

show with ancestor context

ast-outline show <file> <Symbol> prints a # in: ... breadcrumb between the header and the body so you know what the extracted code is nested inside, without a second outline call:

# Player.cs:30-48  Game.Player.PlayerController.TakeDamage  (method)
# in: namespace Game.Player → public class PlayerController : MonoBehaviour, IDamageable
/// <summary>Apply damage.</summary>
public void TakeDamage(int amount) { ... }

---

Architecture & Development

See the wiki/ directory for details on how ast-outline leverages ast-grep internally and how you can add new language adapters.

git clone https://github.com/dim-s/ast-outline.git
cd ast-outline

cargo run -- digest src/

Contributions welcome.

---

License

MIT