| name | hex-summarize |
| description | Generate token-efficient AST summaries of source files. Use when the user asks to "summarize project", "ast summary", "token context", "generate context", "project overview", or "what does this project do". |
Hex Summarize — Tree-Sitter AST Summaries for LLM Context
Generates tree-sitter AST summaries at configurable detail levels, compressing source files to ~10% token count while preserving structural information needed for code generation and navigation.
Parameters
Ask the user for:
- target (optional, default: "."): File or directory path to summarize
- level (optional, default: L1): Summary detail level (L0, L1, L2, or L3)
- format (optional, default: text): Output format —
text, json, or markdown
- filter (optional): Glob pattern to filter files (e.g.,
**/*.ts, src/adapters/**)
- max_tokens (optional, default: 50000): Maximum total tokens for output
- include_tests (optional, default: false): Whether to include test files
Summary Levels Explained
| Level | Name | Tokens/File | What It Captures |
|---|
| L0 | Index | ~5 | Filename, language, line count |
| L1 | Skeleton | ~50 | Exports, imports, dependencies |
| L2 | Signatures | ~200 | Full type signatures, params, return types |
| L3 | Full | ~2000 | Complete source code (use sparingly) |
Execution
1. Discover Files
Find all source files (.ts, .go, .rs) in the target path, excluding node_modules, dist, target, and optionally test files.
2. Run hex summarize
For a single file:
npx hex summarize <file> --level <L0|L1|L2|L3>
For a directory:
npx hex summarize <directory> --level <L0|L1|L2|L3>
If a filter is specified, apply it to limit which files are summarized.
3. Token Budget Management
Estimate tokens using word_count * 1.3 heuristic. If total exceeds max_tokens:
- Drop L2 files to L1
- Drop L1 files to L0
- Prioritize: ports > domain > adapters > infrastructure
4. Format Output
- text: Plain text with
--- separators between files
- json: Structured JSON with filePath, language, level, exports, imports, dependencies, lineCount, tokenEstimate per file
- markdown: Table format with file, language, lines, tokens, exports columns
5. Write Output
Display the summary to the user. If json or markdown format, also write to docs/context/{level}-summary.{ext}.
Output
Report: level used, number of files summarized, estimated token count, and compression ratio (original tokens vs summary tokens).
