Get Started
Quick Reference
The LeanCTX commands and MCP tools you reach for daily: reads, search, shell, session, memory and proof — one page, copy-paste ready.
Your cheat sheet for daily use. For detailed explanations, follow the links to each section's dedicated page.
Read Mode Decision Tree
Which ctx_read mode should the AI use?
| Situation | Mode | Typical savings |
|---|---|---|
| File you'll edit | full | Re-reads: ~99% |
| Context only (code deps/structure or config/doc outline) | map | ~93% |
| API surface (fn/class signatures) | signatures | ~95% |
| After editing a file | diff | ~98% |
| Browse a large file | aggressive | ~85% |
| Very large file, few relevant lines | entropy | ~90% |
| Task-relevant lines only | task | ~77% |
| API docs and reference lookup | reference | ~80-95% |
| Specific line range (surgical) | lines:N-M | ~90-99% |
| Automatic (default - best mode per file) | auto | ~70-99% |
Context Tools (what the AI uses)
These are called by the AI automatically — you don't type them.
| Tool | Purpose | Savings |
|---|---|---|
ctx_read | Read file with compression + caching | up to 99% |
ctx_shell | Execute command with output compression | 60–95% |
ctx_search | Code search with compact results | 50–80% |
ctx_session | Cross-chat session memory | 99% cold-start |
ctx_graph | Dependency graph visualization | - |
ctx_smells | Code smell detection with graph scoring | - |
CLI Commands (what you type)
Essential
| Command | What it does |
|---|---|
lean-ctx setup | One-time setup - detects shell + AI tools, installs everything |
lean-ctx gain | Savings dashboard (--live, --graph, --daily) |
lean-ctx doctor | Diagnose installation, providers, and MCP bridge configuration |
lean-ctx dashboard | Web dashboard with charts (localhost:3333) |
lean-ctx knowledge <action> | Project knowledge: remember, recall, search, export, import, remove, status, health |
lean-ctx benchmark run [path] | Real token savings measurement |
lean-ctx smells | Detect code smells (long functions, deep nesting, high complexity) with graph-enriched scoring |
lean-ctx control | Manage session control settings (compression level, read modes, budgets) |
lean-ctx plan | Generate a task execution plan with file relevance ranking and suggested read order |
lean-ctx compile | Compile context packages (.ctxpkg) from project files into shareable bundles |
lean-ctx graph status | Show project graph stats (nodes, edges, file catalog) |
lean-ctx graph related <file> | Find files related to the given file |
lean-ctx graph impact <file> | Analyze impact of changes to a file |
lean-ctx gain --wrapped | Your token-savings "Wrapped" recap (--period=week|month|all; share via --svg/--share) |
lean-ctx savings <summary|roi|export|team> | Signed, tamper-evident savings ledger — summary, ROI, export and team roll-up |
lean-ctx finops export | Export costs/savings for FinOps platforms (--target=focus|cbf|vantage) |
lean-ctx learning <status|export|import> | Inspect, share and merge adaptive-learning state |
lean-ctx cache <stats|prune|invalidate|clear|reset> | Inspect and maintain the session cache |
lean-ctx allow <cmd> | Add/list/remove commands in your shell allowlist extension (--list/--remove) |