ast-outline 0.8.5

AST-based structural outline for source files (C#, C++, Python, TypeScript/JavaScript, Java, Kotlin, Scala, Go, Rust, PHP, Ruby, CSS, SCSS, SQL, Markdown, YAML) — tree-sitter-powered, LLM-agent-first. Outlines, digests, and structural code-grep with scope+kind annotations.

ast-outline

English · Русский · 简体中文

Stateless CLI that prints the structural shape of a source file — classes, methods, signatures, line ranges — without method bodies. Plus an AST-aware structural code-grep with scope and kind annotations. Built so LLM coding agents stop reading whole files just to answer "what's in here?".

📖 Full documentation: https://ast-outline.github.io/

---

Why

LLM coding agents (Claude Code, Cursor agent mode, Aider, Codex CLI, Gemini CLI, Copilot Chat) explore codebases by reading files directly. Reliable, but wasteful in two ways: a 1200-line file costs 1200 lines of context just to answer "what methods are in here?" — and once the noise is in context, the agent has to wade through it to find the part that actually matters. Token cost goes up, comprehension goes down.

ast-outline is a pre-reading layer. The agent calls it first, gets the file's shape in 60–100 lines, and only opens the bodies it actually needs. The win is double: fewer tokens in context, and sharper comprehension — less noise to filter through means the agent locks onto the relevant code faster and answers with less drift.

Before:

Agent: Read Player.cs              # 1200 lines, just to see what's here
Agent: Read Enemy.cs               #  800 lines, just to see what's here
Agent: grep -rn TakeDamage src/    # flat hits → open each file for scope
Agent: Read DamageSystem.cs        #  400 lines, all to read one method

With ast-outline:

Agent: ast-outline digest src/Combat         # whole module map, ~100 lines
Agent: ast-outline Player.cs                 # one file's shape, 2–10× smaller
Agent: ast-outline grep TakeDamage src/      # uses + scope, one call (no follow-ups)
Agent: ast-outline show Player.cs TakeDamage # just that one method body

Sharper understanding (less noise to filter), a fraction of the tokens, a fraction of the round-trips.

---

Who this is for

• You use an LLM coding agent on a real codebase and feel the token cost.
• You want a drop-in CLI, not another vector index, MCP server, or daemon.
• You're happy with the agent chaining ast-outline with grep, find, ast-grep — Unix-style — instead of a bespoke RAG layer.

If you fit any of those, the rest of this README is for you.

---

Install

uv tool install ast-outline

Installs the ast-outline CLI globally. No uv?

curl -LsSf https://astral.sh/uv/install.sh | sh                                          # macOS / Linux
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"       # Windows

Other install paths (pipx, pip, source, bundled script)

pipx install ast-outline
pip  install ast-outline                                          # into an active venv

# Latest main instead of the PyPI release:
uv tool install git+https://github.com/ast-outline/ast-outline.git

# Bundled one-shot installer (also installs uv if missing):
curl -LsSf https://raw.githubusercontent.com/ast-outline/ast-outline/main/scripts/install.sh | bash    # macOS / Linux
iwr -useb https://raw.githubusercontent.com/ast-outline/ast-outline/main/scripts/install.ps1 | iex     # Windows

Update / uninstall: uv tool upgrade ast-outline / uv tool uninstall ast-outline.

---

30-second tour

# Structural outline of one file
ast-outline path/to/Player.cs

# Outline a whole directory (recursive, mixed languages OK)
ast-outline src/

# Compact one-page map of a module
ast-outline digest src/Services

# Pull the source of one method (or several at once)
ast-outline show Player.cs TakeDamage
ast-outline show Player.cs TakeDamage Heal Die

# Find every place a symbol appears, with scope + kind
ast-outline grep User.save src/

# Built-in guide
ast-outline help

---

Wire it into your coding agent

This is the main use case. The agent learns about ast-outline from a snippet in your AGENTS.md / CLAUDE.md / GEMINI.md. Two paths to install it.

Automatic (recommended). Inside Claude Code / Codex CLI / Gemini CLI / Cursor, ask the agent:

Run ast-outline setup-prompt and follow its instructions.

The agent verifies the install, picks the right context file for your tooling (AGENTS.md cross-tool default, CLAUDE.md / GEMINI.md for single-vendor), appends the snippet inside <!-- ast-outline:start --> ... <!-- ast-outline:end --> markers (diff-aware on re-run, won't overwrite your edits), and optionally patches exploration subagents in .claude/agents/ / .codex/agents/ / .gemini/agents/.

Manual. Pipe the same snippet wherever you want:

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

Heads up — Claude Code subagents. CLAUDE.md / AGENTS.md reach the main agent only. Built-in subagents like Explore see only their own system prompt; shadow them with .claude/agents/Explore.md containing the ast-outline prompt body. Cursor, Aider, and direct API clients have no isolated subagents — CLAUDE.md is enough there.

---

Supported languages

Language	Extensions
C#	.cs
C++	.cpp, .cc, .cxx, .c++, .h, .hpp, .hh, .hxx, .h++, .ipp, .tpp, .inl, .cppm, .ixx (incl. Unreal Engine UCLASS / UFUNCTION / GENERATED_BODY)
Python	.py, .pyi
TypeScript	.ts, .tsx
JavaScript	.js, .jsx, .mjs, .cjs (parsed by the TypeScript grammar)
Java	.java
Kotlin	.kt, .kts
Scala	.scala, .sc (Scala 2 + Scala 3)
Go	.go
Rust	.rs
PHP	.php, .phtml, .phps, .php8 (PHP 8.x + 7.4 LTS; tested on WordPress core)
Ruby	.rb, .rake, .gemspec, .ru, Rakefile, Gemfile (incl. Rails associations)
CSS	.css
SCSS	.scss
SQL	.sql (PostgreSQL primary; MySQL / SQLite usable)
Markdown	.md, .markdown, .mdx, .mdown
YAML	.yaml, .yml (Kubernetes / OpenAPI / GitHub Actions detected)

Per-adapter feature detail (which constructs each adapter recognises, how inheritance is rendered, what's collected as imports, …) lives in the docs site: https://ast-outline.github.io/.

Adding a new language is one new file under src/ast_outline/adapters/ — see AGENTS.md for the lockstep checklist.

---

Commands

Each command takes one or more paths (files or directories, mixed languages fine). All flags and the full output format reference live in the docs.

• outline <paths…> — default. Signatures with L<start>-<end> line ranges, no bodies. Add --imports to surface each file's import / use / using line in native syntax. Filters: --no-private, --no-fields, --no-docs, --no-attrs.

• digest <paths…> — one-page module map. Each file gets a size label ([tiny] / [medium] / [large] / [huge]) and a token estimate; type headers carry inheritance (: Base, Trait) and decorators (@dataclass, [ApiController]). The first line of output is a self-describing legend so an LLM reads it cold. [huge] files (≥100k tokens) collapse to header-only.

• show <file> <Symbol> [Symbol…] — extract one or more bodies by name. Suffix matching for code (Foo.Bar matches *.Foo.Bar); case-insensitive substring for Markdown headings; dotted key path for YAML; selector token for CSS / SCSS; table or table.column for SQL. --signature returns header only.

• grep <pattern> <paths…> — AST-aware structural search. Matches grouped by enclosing class / function, with kind tags [def] / [import] (calls and refs render untagged — the ( after the symbol makes them obvious). Comment / string noise filtered by default. POSIX flags -e (multi-pattern, one walk), -w, -l, -c, -m, -i work as in grep / rg. Regex is auto-detected. --kind def|call|ref|import narrows by classification.

• prompt — print the canonical agent-context snippet (used by setup-prompt). Manual install path: ast-outline prompt >> AGENTS.md.

• setup-prompt — emit an install-time checklist for an LLM agent to walk you through wiring ast-outline into your tooling. The CLI itself does no file I/O — every edit is performed by the agent using its own tools, so each change is reviewable.

• help [topic] — built-in usage guide.

CLI exit-code contract. User-facing failures (file not found, no match, bad arg) print a # note: … line to stdout and exit 0. This is deliberate — non-zero exits break parallel bash batches in agent harnesses. Real internal crashes still propagate normally.

---

Design

• Stateless. No index, no cache, no embeddings, no network. Parse on demand, print, exit.
• AST, not regex. Built on tree-sitter — type headers carry real : Base, Trait inheritance, show finds the actual symbol, comments and string literals don't trigger false positives.
• No MCP server. For a stateless CLI an agent gets more leverage piping and parallelising it in bash than through an MCP shim wrapping the same calls.

Naming inspired by ast-grep — both build on tree-sitter, but ast-grep rewrites code with structural patterns, ast-outline maps and searches it for human / agent reading.

---

Development

git clone https://github.com/ast-outline/ast-outline.git
cd ast-outline
uv venv && uv pip install -e ".[dev]"
.venv/bin/pytest                  # full suite
.venv/bin/ast-outline tests/sample.py

Adapters live under src/ast_outline/adapters/; fixtures under tests/fixtures/<lang>/; per-adapter tests under tests/unit/test_<lang>_adapter.py. New behaviour ships with a test. Adding a language? See AGENTS.md for the checklist (five files change together).

---

License & attribution

What	License
Code v0.6.0+	Apache 2.0
Code ≤ v0.5.3	MIT (preserved for downstream forks)
Documentation & prose (READMEs, CLI help, prompt snippet, digest legend)	CC BY 4.0

Both licenses are permissive — fork, ship commercially, port. The split makes attribution requirements explicit. If you reuse non-trivial prose from this documentation, CC BY 4.0 asks for visible credit:

Based on ast-outline by Dmitrii Zaitsev (dim-s), licensed under CC BY 4.0.

Copyright © 2026 Dmitrii Zaitsev (dim-s) and ast-outline contributors. The ast-outline GitHub org is hosting only.

For history (releases, renames, license change), see CHANGELOG.md and GitHub Releases.