Analytics, Insights & Reporting

How much is LeanCTX actually saving you? Where is context being wasted? Which commands are slow? This journey covers every reporting, measurement, and “show me the numbers” surface — without ever costing the agent extra tokens (all of this is CLI / dashboard, not injected context).

0. The principle

Per the project’s own rule: LeanCTX never prints “↓80% saved” into agent context — that would burn tokens. Savings live here, in the CLI and dashboard, where a human looks at them.

So analytics is a pull model: nothing is added to your agent’s window; you run a command when you want the numbers.

1. gain — the savings dashboard

lean-ctx gain is the single entry point, with one mode per question:

lean-ctx gain                      # headline savings summary

Flag	Answers
--live (--watch)	live-updating savings as you work
--graph	savings over time, sparkline
--daily	per-day breakdown
--cost	dollar cost saved (model-priced)
--score	efficiency score
--tasks	savings grouped by task
--agents	savings grouped by agent (see Journey 8)
--heatmap	which files/commands save the most
--wrapped	”Spotify Wrapped”-style recap
--pipeline	provider-pipeline processing stats
--deep	everything: report + tasks + cost + agents + heatmap
--json	machine-readable (for scripts/CI)
--reset	clear all savings data

Refinements: --model <name> (price against a specific model), --period <p> (time window, default all), --limit <n> (rows, default 10).

Start with lean-ctx gain; reach for --deep when you want the full picture in one shot, or --cost --model gpt-4o to put a dollar figure on it.

2. wrapped — the shareable recap

lean-ctx gain --wrapped            # (lean-ctx wrapped is a deprecated alias)

A celebratory, screenshot-friendly summary of tokens/cost saved over a period — good for sharing with your team or justifying the tool to a lead. Turn it into something you can post:

Flag	Shares as
--svg [=<path>]	an SVG card (social / OG image), default lean-ctx-wrapped.svg
--share [=<path>]	a self-hostable HTML page with social-preview meta
--copy	a ready-to-post share line copied to your clipboard
--open	with --svg/--share: opens the card/page in your browser
--publish [--name=<n>]	an opt-in permalink at leanctx.com/w/<id> (URL copied)
--publish --leaderboard	also lists the card on the opt-in public leaderboard
--unpublish[=<id>]	removes a published permalink (most recent if no id)

Sharing is opt-in and privacy-safe: only a whitelisted, aggregate slice (tokens saved, USD estimate, period, compression rate, command/session/file counts, tool names, optional model, optional display name) is published — never code, paths, or prompts. A one-time edit token is stored locally so you can --unpublish later.

3. token-report — tokens + memory

lean-ctx token-report              # tokens saved + memory footprint
lean-ctx token-report --json

Where gain focuses on savings, token-report (alias report-tokens) adds the memory side: how much session/knowledge/cache state LeanCTX is holding.

Golden output — lean-ctx token-report combines the knowledge store, the live session, and the latest CEP scorecard in one view:

lean-ctx token-report  v3.6.26
  project: /Users/you/dev/lean-ctx
  data:    /Users/you/.lean-ctx
  knowledge: 105 active, 97 archived, 0 patterns, 91 history
  session: 1953 calls, 90710600 tok saved, 333 files read (17 repeated)
  cep(last): score=66 cache_hit_rate=18 mode_diversity=100 compression_rate=82 tok_saved=284748
  report saved: /Users/you/.lean-ctx/report/latest.json

The cep(last) line is the most recent Context Engineering Protocol scorecard (see §9); 17 repeated reads are the cache wins that cost ~13 tokens each.

4. Finding waste — discover and ghost

lean-ctx discover                  # commands in your shell history that ran uncompressed
lean-ctx ghost                     # "ghost tokens": hidden waste lean-ctx could catch
lean-ctx ghost --json

• discover scans shell history for commands you ran without LeanCTX — your “you could have saved more here” list. On its first run it projects a concrete saving for the current project (a one-time “aha”); add --card to export a shareable “before lean-ctx” SVG.
• ghost quantifies waste that’s currently slipping through, so you know whether tightening compression (Journey 10) is worth it.

5. Performance — slow-log

lean-ctx slow-log list             # slowest commands lean-ctx wrapped
lean-ctx slow-log clear

If LeanCTX ever feels like it’s adding latency, this tells you exactly which commands were slow to compress, so you can exclude or filter them.

6. Output logs — tee

lean-ctx tee list                  # captured output logs
lean-ctx tee last                  # the most recent
lean-ctx tee show <id>
lean-ctx tee clear

tee keeps a log of compressed command outputs so you can recover the full output of something you ran earlier without re-running it.

7. The web dashboard — dashboard

lean-ctx dashboard                 # http://localhost:3333
lean-ctx dashboard --port 4000 --host 0.0.0.0

A browser UI over everything in this journey: live savings, heatmaps, sessions, knowledge, agents. The richest way to explore; ideal for a second monitor.

The dashboard is where context-management visualization lives — distinct from the raw CLI numbers.

8. The live TUI — watch

lean-ctx watch                     # real-time event stream in the terminal

A terminal dashboard (no browser) showing the live event stream — reads, compressions, cache hits — as they happen. Great for confirming “is LeanCTX actually intercepting this?” in real time.

9. Quality scoring — cep and benchmark

lean-ctx cep                       # CEP score trends (Context Engineering Protocol)
lean-ctx benchmark run             # run the benchmark suite
lean-ctx benchmark report          # results
lean-ctx benchmark eval / compare  # evaluate / compare runs

• cep tracks the Context Engineering Protocol score over time — a measure of how well-structured the agent’s context has been.
• benchmark measures compression quality/throughput so regressions are caught (also used in CI, Journey 9).

10. Learning loops — learn and gotchas

These turn observed history into durable insight:

lean-ctx gotchas list              # recorded bugs/footguns ("bug memory")
lean-ctx gotchas stats / export / clear
lean-ctx learn                     # learned gotchas
lean-ctx learn --apply             # promote them into AGENTS.md

• gotchas (alias bugs) is a memory of mistakes/footguns hit in this project.
• learn --apply promotes high-value lessons into your agent rules — the analytics-to-governance bridge (pairs with export-rules, Journey 10).

11. Raw stats & transcript compaction

lean-ctx stats                     # raw stats store summary
lean-ctx stats json                # raw JSON
lean-ctx stats reset-cep           # reset CEP scores only
lean-ctx compact [path]            # compress stored agent transcripts

stats is the low-level store behind gain; compact shrinks saved agent transcripts so long histories don’t bloat the data dir.

12. Decision guide

You want…	Reach for
Headline savings	gain (§1)
A shareable recap	wrapped (§2)
Tokens and memory footprint	token-report (§3)
Where am I still wasting tokens?	discover, ghost (§4)
Is LeanCTX slowing me down?	slow-log (§5)
Recover an earlier full output	tee (§6)
Rich visual exploration	dashboard (§7)
Watch it work live	watch (§8)
Context-quality / regression tracking	cep, benchmark (§9)
Turn history into rules	learn, gotchas (§10)
Raw numbers / shrink transcripts	stats, compact (§11)

Storage & data (analytics)

Path	Contents
~/.lean-ctx/ stats store	savings/usage that gain/stats read
~/.lean-ctx/pipeline_stats.json	provider-pipeline stats (gain --pipeline)
tee logs	captured full command outputs
gotchas/bug memory	recorded footguns