Token Optimization

Reduce Claude token usage by ~60–85%

Stop Claude from reading raw source files. Give it a pre-built symbol map instead.

Why Claude uses so many tokens

By default, Claude Code reads your source files directly to understand the codebase. A typical TypeScript file is 200–400 lines — around 600 tokens. For a 200-file project, just exploring the structure can cost 100,000+ tokens before Claude writes a single line.

How larkx fixes it

larkx pre-indexes every file, function, class, import, and call relationship into a compact graph. Claude reads the graph — not the files. Instead of 600 tokens per file, it costs ~80 tokens at level 2. Claude only opens actual source files when it needs to edit them.

Estimated token savings by project size

Project size	Reading files directly	larkx level 2	Reduction
50 files	~30,000 tokens	~4,000 tokens	~87%
200 files	~120,000 tokens	~16,000 tokens	~87%
500 files	~300,000 tokens	~40,000 tokens	~87%

~600 tokens/file average for direct reads. Savings vary by project size and task type.

Run larkx stats after indexing to see exact token estimates at each level for your own project.

Token cost per tool call

Question	Cheapest call	Approx tokens
"What files exist?"	`get_project_index level=1`	~8 per file
"Where is function X?"	`search_symbol`	~30 total
"What's in this file?"	`get_file_summary`	~100 total
"What imports this?"	`get_impact`	~100 total
"What calls what?"	`get_call_chain`	~100 total
"What's unused?"	`get_dead_code`	~200 total

The three levers

Context level (1–4) — controls detail per file. Level 1 is paths only (~8 tok/file). Level 2 adds symbols (~80 tok/file). Start cheap, go deeper only if needed.
Folder scoping — restrict get_project_index to a subfolder. Working in src/auth? Only load that subtree.
Tool choice — use search_symbol instead of get_project_index when you just need to find one function. 30 tokens vs thousands.

What does level 2 look like?

bash

# larkx context · level 2 · ~681 tokens · 17 files
src/auth/login.ts[typescript]: validateJWT@6, hashPassword@12, login@17 | +../utils/crypto,+../db/users
src/auth/middleware.ts[typescript]: authMiddleware@9, rateLimiter@19 | +./login
src/db/users.ts[typescript]: findById@8, create@18, UserRepository@7 | +../utils/logger
src/utils/crypto.ts[typescript]: sha256@3, generateToken@7, compareHash@11 | +crypto
src/utils/legacy.ts[typescript]: oldEncrypt@2

Claude gets function names, line numbers, and imports for every file in ~681 tokens. Reading those same 5 files directly would cost ~3,000+ tokens.

Try it on your project

Project size200 files

Folder scope100% · 200 files

Level	Includes	Tokens	Savings
L1Paths	Just file paths + language	~1.6K	−99%
L2Symbols	+ function & class names + imports	~16K	−87%
L3Signatures	+ full function signatures	~30K	−75%
L4Summaries	+ one-line AI summary per file	~50K	−58%
Reading every file directly		~120K	baseline

Estimated best case≈ 99% reduction · level 1 + scoping

Heads up, this is an estimate, not a measurement. Numbers assume ~3.5 characters per token, an average file size of ~2 KB, and average symbol counts. Your actual savings depend on your AI's tokenizer (Claude/GPT/Gemini differ), file size distribution, and how the agent uses tools. Treat these figures as ballpark, use larkx stats in your project for indexed estimates that better match your codebase.

See best practices for prompt patterns that keep Claude picking the cheapest tool automatically.