Token Optimization
Context levels (1-4)
Tier the detail to fit the question.
The four levels
Level 1, Paths only
Just file path and language. ~8 tokens per file. Best for "what files exist".
bash
# larkx context · level 1 · ~270 tokens · 34 files
src/auth/login.ts[ts]
src/auth/middleware.ts[ts]
src/auth/session.ts[ts]
...Level 2, Symbols + imports (default)
File path, function names, class names, line numbers, imports. ~80 tokens per file. Balanced for general exploration.
bash
# larkx context · level 2 · ~2.7K tokens · 34 files
src/auth/login.ts[ts]: validateJWT@6, hashPassword@10, LoginService@14 | +../utils/crypto,+../db/users
src/auth/middleware.ts[ts]: authMiddleware@11, rateLimiter@20 | +./login
...Level 3, Signatures
Same as level 2 but functions show full signatures. ~150 tokens per file. Use before refactoring.
bash
# larkx context · level 3 · ~5.1K tokens · 34 files
src/auth/login.ts[ts]: function validateJWT(token: string): boolean@6, function hashPassword(pw: string): Promise<string>@10, class LoginService@14 | +../utils/crypto,+../db/users
...Level 4, + AI summaries
Adds Claude Haiku-generated one-line summaries. ~250 tokens per file. Use for architectural understanding.
bash
# larkx context · level 4 · ~8.5K tokens · 34 files
// Handles JWT validation and bcrypt password hashing
src/auth/login.ts[ts]: function validateJWT(token: string): boolean@6, ...
...Picking the right level
| Task | Best level |
|---|---|
| "Show me the project layout" | 1 or 2 |
| "Where is X defined?" | 2 (or just search_symbol) |
| "Refactor function X across all callers" | 3 |
| "Explain how authentication works in this app" | 4 |
Level 4 needs --ai indexingSummaries are only present if you ran
larkx index --ai. Otherwise level 4 gracefully falls back to level 3 output.