Why use larkx?
The token math, real benchmarks, and when larkx is not the right tool.
The token problem
AI tokens have a real dollar cost. A typical project file can be several hundred tokens, so reading a whole codebase can become tens to hundreds of thousands of tokensvery quickly. At Claude Sonnet pricing (~$3 per million tokens), a full scan can easily become a few tenths of a dollar on a medium project, and the real number is often higher once the agent re-reads files across turns.
Most AI tasks do not need every file. The agent usually discovers that only after it has explored. That means repeated reads, context loss after compaction, and extra turns can multiply the cost beyond the theoretical minimum.
larkx's answer
- Level 1 (paths + language): about 8 tokens per file. 300 files = about 2.4K tokens.
- Level 2 (+ symbols + imports): about 80 tokens per file. 300 files = about 24K tokens.
- Level 3 (+ full signatures): about 150 tokens per file. 300 files = about 45K tokens.
- Level 4 (+ AI summaries): about 250 tokens per file. 300 files = about 75K tokens.
- Folder scoping: the savings are usually proportional to how much of the project you scope down to, so narrowing to one subsystem often cuts the bill sharply.
Measure for your project
Run larkx bench after indexing. It reports real token usage from Claude, not estimates. The cheapest sanity check is larkx bench --only=overview and you can compare that result against your own workflow.
When larkx helps the most
- Projects with 100+ files where the AI cannot cheaply read everything each time
- Refactors and dependency questions, where
get_impactis cheaper than repeatedly reading and re-reading files - Onboarding to unfamiliar codebases, where level 4 summaries can help the AI form a first-pass understanding
- Dead code cleanup, where reachability-based detection is often more useful than scanning for unused symbols manually
When it might not be worth it
- Tiny projects, where the AI can read the whole thing quickly
- One-off scripts or very narrow tasks where indexing overhead may outweigh the savings
- Projects with unsupported languages or a workflow that does not benefit from structured graph queries
Quick comparison
| Approach | Initial scan | Per refactor | Accuracy |
|---|---|---|---|
| Plain AI reading files | Often tens of thousands to 180K+ tokens | Often several thousands to tens of thousands | Partial, depends on what it opens |
| Grep / find tools | Roughly 10K tokens or less | Low | Pattern-only, no semantic graph |
| larkx (L2) | About 24K tokens | Usually low | Structured symbol + dependency context |
Bottom line
larkx is a strong fit when you use AI agents for code repeatedly and your project is larger than a single folder or a few files. It is free, open-source, and runs entirely on your machine. It is not a universal replacement for direct file reads, and the best choice still depends on your project size, language support, and the kinds of tasks you run.