AST-based file TOC generator for AI coding agents.
Instead of reading files in full, agents read a compact Table of Contents first, then fetch only the functions or classes they actually need. This reduces token usage by ~86% per file and ~44% per task compared to reading everything.
agent reads TOC(auth.py) → 150 tokens
[class] JWTAuth (L12) — handles token validation
[fn] verify (L18)
[fn] refresh (L34)
[fn] decode_token (L89)
agent reads auth.py L18-33 → 200 tokens ← only what it needs
vs. reading the full file: 2,000 tokens.
git clone https://github.com/yourname/agentfs
cd agentfs
pip install -e .No external dependencies — uses stdlib ast only.
# Print TOC of any source file
agentfs toc src/auth.py
# Benchmark token savings on a codebase
agentfs benchmark /path/to/project
agentfs benchmark /path/to/project --threshold 0.4Add to .claude/commands/toc.md in your project:
Run the following command and show the output:
```bash
agentfs toc $ARGUMENTS
```
Use the TOC to understand the file structure, then read only the specific
functions or classes you need using the Read tool with line offsets.Then use it as:
/toc src/auth.py
| Language | Method |
|---|---|
| Python | ast module (precise) |
| JS / TS / JSX / TSX | regex |
| Go / Rust / Java / C / C++ | regex |
| Markdown / YAML / JSON / TOML | content preview |
Tested on Flask (src/flask/, 25 files, 50k tokens):
| Strategy | Tokens saved vs baseline |
|---|---|
| Read everything | — |
| Grep + read matches | −36% |
| TOC-first (adaptive) | −44% |
Per-task savings range from −7% (generic terms like error) to −86%
(specific terms like authentication).
See SUMMARY.md for the full analysis.
MIT