Documentation

Analytics & Dashboards

How to monitor token savings, interpret dashboards, run benchmarks, and share reports.

lean-ctx tracks every token it saves across all sessions. This guide explains how to access, interpret, and share your savings data through terminal dashboards, web UI, wrapped reports, and benchmarks.

All data is stored locally at ~/.lean-ctx/stats.json and persists across sessions and restarts.

Terminal Dashboard - lean-ctx gain

The primary way to check your savings. Run lean-ctx gain in any terminal to see a visual dashboard with colors, bars, sparklines, and USD estimates.

$ lean-ctx gain

  ◆ lean-ctx  Token Savings Dashboard
  ────────────────────────────────────────────────────────

   7.8M          67.8%          3,994        $43.14
   tokens saved  compression    commands     USD saved

  Top Commands
  ──────────────
  curl     328x  ████████████████████  3.2M saved
  git      412x  ██████████████        1.8M saved
  cargo    156x  ██████████            1.1M saved
  npm       89x  ████                  420K saved

  30-day sparkline: ▁▃▅▇██▇▅█▇▃▁▅▇██▇▅█▇▃▁▅▇██▇▅█▇▃▁▅▇██▇▅█▇▃▁

What the numbers mean

MetricMeaning
tokens savedTotal tokens stripped from LLM context across all sessions.
compressionAverage percentage of tokens removed. Higher = more efficient.
commandsTotal shell commands compressed by the shell hook.
USD savedEstimated cost savings based on average token pricing ($2.50/1M input tokens).
Top CommandsWhich CLI tools saved the most tokens, ranked by total savings.
30-day sparkline30-day visual trend of daily savings activity.

Live Mode - lean-ctx gain --live

Auto-refreshing dashboard that updates every 2 seconds.

$ lean-ctx gain --live

  ◆ lean-ctx  LIVE  refreshing every 2s
  ────────────────────────────────────────────────────────

   7.8M          67.8%          3,994        $43.14
   tokens saved  compression    commands     USD saved

  Session: 42 cmds | 89.2K saved | 94.1% rate ▁▃█▇██▁█

  Press q to quit

When to use: Run in a side terminal during coding sessions to monitor savings as they happen.

Charts & Tables

lean-ctx gain --graph

30-day savings chart with daily bars.

$ 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 gain --daily

Bordered day-by-day table with columns for tokens saved, compression rate, command count, and USD.

$ lean-ctx gain --daily

  ┌────────────┬──────────┬───────┬──────┬────────┐
  │ Date       │ Saved    │ Rate  │ Cmds │ USD    │
  ├────────────┼──────────┼───────┼──────┼────────┤
  │ 2026-03-28 │ 1.7M     │ 72.4% │ 412  │ $4.25  │
  │ 2026-03-27 │ 1.1M     │ 68.9% │ 289  │ $2.75  │
  │ 2026-03-26 │ 690K     │ 71.2% │ 187  │ $1.73  │
  └────────────┴──────────┴───────┴──────┴────────┘

Web Dashboard - lean-ctx dashboard

Interactive browser-based dashboard at http://localhost:3333.

lean-ctx dashboard              # default port 3333
lean-ctx dashboard --port=8080  # custom port

Dashboard panels

PanelContent
Stats OverviewTotal tokens saved, compression rate, USD, command count - same data as gain
MCP ActivityRecent MCP tool calls, which tools are used most, response times
Active AgentsAI agents currently registered via ctx_agent. Shows agent name, role, status, and heartbeat.
Project KnowledgeFacts stored via ctx_knowledge, grouped by category with confidence scores.

API endpoints

The dashboard serves a JSON API that you can query directly:

EndpointData
GET /api/statsToken savings stats (same as gain --json)
GET /api/mcpMCP tool usage data
GET /api/agentsActive agent registry
GET /api/knowledgeProject knowledge store

Wrapped Reports - lean-ctx wrapped

"Spotify Wrapped" for your token savings. Generates a shareable report card.

lean-ctx wrapped           # current week
lean-ctx wrapped --week    # current week (explicit)
lean-ctx wrapped --month   # current month
lean-ctx wrapped --all     # lifetime stats

Example output

$ lean-ctx wrapped --month

  ◆ 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

  Best day: March 24 - 1.7M tokens saved
  Most used mode: map (42% of reads)

CEP Report - lean-ctx cep

The Cognitive Efficiency Protocol report shows how lean-ctx optimizes LLM reasoning.

$ lean-ctx cep

  CEP Impact Report
  ────────────────────────────────

  Score trend:  ▁▃▅▇██▇█  (improving)
  Cache hits:   94.2% (re-reads served from cache)
  Mode distribution:
    full:        42%  ████████████████
    map:         31%  ████████████
    signatures:  18%  ███████
    diff:         9%  ███

Benchmarking

Measure exact token savings on real project files using tiktoken.

lean-ctx benchmark run [path] [--json]

$ lean-ctx benchmark run src/

  Benchmarking 42 files...

  src/auth.ts (123 lines)
    full:       3,517 tokens
    map:          412 tokens (88% saved)
    signatures:   252 tokens (93% saved)
    entropy:      312 tokens (91% saved)

  src/server.ts (456 lines)
    full:       8,234 tokens
    map:          891 tokens (89% saved)
    signatures:   534 tokens (94% saved)

  ── Summary ──────────────────────
  42 files | 89,412 total tokens
  Average savings: map 87% | signatures 92% | entropy 85%

lean-ctx benchmark report [path]

Generate a Markdown report you can share or commit to your repository.

lean-ctx benchmark report src/ > BENCHMARK.md

The report includes per-file breakdowns, mode comparisons, and aggregate statistics.

JSON Export - lean-ctx gain --json

Export all statistics as JSON for scripting, CI/CD integration, or custom dashboards.

lean-ctx gain --json > stats.json

The JSON includes:

  • Total tokens saved and compression rate
  • Per-command breakdown (command name, count, tokens saved)
  • Daily history (date, saved, rate, commands)
  • USD estimates

Example: extract total savings in a CI script:

SAVED=$(lean-ctx gain --json | jq '.total_saved')
echo "lean-ctx saved $SAVED tokens this session"

USD Calculation

lean-ctx estimates USD savings based on average LLM input token pricing. The default rate is $2.50 per 1M input tokens.

The formula is:

USD saved = (tokens saved / 1,000,000) × $2.50

This is a conservative estimate - actual savings may be higher if you use more expensive models or lower if you use cheaper models.