CLI Reference

Commands for Humans.
Results for AI.

lean-ctx works automatically after setup. But when you want control, these commands are waiting.

The essentials

Essential Commands

lean-ctx setup

One-time setup. Auto-detects your shell (zsh/bash/fish), finds installed AI tools, configures MCP and shell hooks. Run once, never think about it again.

Run once after install
lean-ctx init

Quick setup for a specific AI tool. Use --agent cursor, --agent claude, --agent codex, or --agent gemini to configure MCP for that tool directly.

Per-agent alternative to setup
lean-ctx gain

See your savings dashboard. Lifetime token savings, compression rates, top commands, and USD cost estimates. Persistent across all sessions.

Check anytime
Know exactly what you save

Monitoring & Insights

lean-ctx gain

Lifetime savings dashboard with token counts, compression rate, top commands, and USD cost tracking.

$ lean-ctx gain

โ—† lean-ctx Token Savings Dashboard

โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€

1.7M saved 76.8% rate $4.25 USD

Top Commands

curl 48x โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 728K

git 34x โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 375K

lean-ctx gain --live

Auto-refreshing live dashboard. Updates every 2 seconds as your AI tools save tokens in real time.

โ— LIVE

$ lean-ctx gain --live

โ—† lean-ctx LIVE refreshing every 2s

โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€

1.7M saved โ–โ–ƒโ–ˆโ–‡โ–ˆโ–ˆโ–โ–ˆ

Session: 42 cmds | 89.2K saved | 94.1% rate

Press q to quit

lean-ctx gain --graph

30-day savings chart with daily bars, sparklines, and trend visualization. See your savings trajectory.

$ lean-ctx gain --graph

Token Savings (30 days)

03-20 โ”‚ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 1.0M

03-21 โ”‚ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 690K

03-22 โ”‚ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 1.1M

03-23 โ”‚ โ–ˆ 9.4K

03-24 โ”‚ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 1.7M

lean-ctx dashboard

Web dashboard at localhost:3333. Interactive charts, session history, and real-time monitoring in your browser.

$ lean-ctx dashboard

โ—† lean-ctx Dashboard

โ†’ http://localhost:3333

Interactive charts, session history, command breakdown

Press Ctrl+C to stop

lean-ctx wrapped

"Spotify Wrapped" for your token savings. Beautiful, shareable reports with your lifetime stats, top commands, and personal compression achievements.

weekly monthly lifetime

$ lean-ctx wrapped monthly

โ—† Your March 2026 Wrapped

โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€

4.9M tokens saved

3,241 commands compressed

$12.16 USD saved

Top pattern: curl (97% compression)

You're in the top 5% of lean-ctx users

Verify & optimize

Diagnostics

lean-ctx doctor

Runs 11 installation checks - binary, shell hook, MCP config, stats file, cache directory, supported shell, AI tool detection, version check, rules injection, Claude Code instructions, and build integrity.

โœ“ Binary installed

โœ“ Shell hook active (zsh)

โœ“ MCP config (Cursor)

โœ“ Stats persistence

โœ“ Cache directory

โœ“ Data directory writable

โœ“ Project detection

โœ“ Graph index

โœ“ Search index

โœ“ Agent hooks

โœ“ Version up to date

All 11 checks passed

lean-ctx discover

Scans your shell history for commands that could benefit from compression but aren't being intercepted yet.

Found 12 uncompressed commands:

kubectl - 34 calls, ~89% savings possible

helm - 12 calls, ~76% savings possible

terraform - 8 calls, ~82% savings possible

Run setup to enable these

lean-ctx benchmark run

Measures real token savings in your codebase using tiktoken (o200k_base). Exact numbers, no estimates.

src/auth.ts (123 lines)

full: 3,517 โ†’ 3,517 (0%)

map: 3,517 โ†’ 412 (88%)

signatures: 3,517 โ†’ 252 (93%)

entropy: 3,517 โ†’ 312 (91%)

Full control

Power User Commands

Command Description
lean-ctx init --agent <name> Quick MCP setup for a specific AI tool (cursor, claude, codex, gemini, windsurf, copilot, cline, roo, pi, qwen, trae, amazonq, jetbrains)
lean-ctx read <file> -m <mode> Read any file with a compression mode (full, map, signatures, diff, aggressive, entropy). Cached reads return ~13 tokens. Use --fresh to bypass cache.
lean-ctx diff Compressed git diff - structured output with change summaries
lean-ctx grep <pattern> Token-efficient pattern search with compact context
lean-ctx find <pattern> Find files by name - compact results with file counts
lean-ctx ls Directory listing as a compact tree map
lean-ctx -c "<cmd>" Compress any arbitrary shell command output through lean-ctx
lean-ctx config set <key> <value> Configure lean-ctx settings - checkpoint intervals, cache TTL, CRP mode
lean-ctx cache [stats|clear|invalidate] Manage CLI file cache - view stats, clear entries, or invalidate specific paths
lean-ctx setup One-command setup - configures shell hooks, editor MCP, and verifies everything works
Full configuration reference

Ready to see your savings?

Install lean-ctx, run setup, and start saving tokens immediately. Check your dashboard with gain whenever you want.

Get Started Star on GitHub