Journey: 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 Multi-Agent Collaboration)
--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.

Net of injection. gain reports net_tokens_saved — gross savings minus the tokens LeanCTX itself injects (tool definitions, hints) — alongside the per-turn injected overhead and a one-line methodology note. The headline is the net figure, so it reconciles to your provider bill instead of inflating 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.8.6
  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 (Customization & Governance) 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
lean-ctx dashboard --open=vscode   # reveal control: browser (default) | none | vscode

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 live call feed is sortable (Recent / Top saved / Largest / Slowest) so you can rank tool calls by cost, and a Quick Settings tab flips the high-impact switches — compression level, tool profile, structure_first, terse agent — mid-session without hand-editing config.toml.

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 — see Team, Cloud & Self-Hosting).

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 in Customization & Governance).

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. FinOps export & live metrics

Savings only matter to finance if they land in the cost stack. LeanCTX exports the signed ledger in the formats FinOps teams already consume:

lean-ctx finops export --target=focus    # FOCUS 1.2 CSV (passes the official FinOps validator)
lean-ctx finops export --target=cbf      # CloudZero AnyCost
lean-ctx finops export --target=vantage  # Vantage

Output is net-of-injection (net_tokens_saved), so a showback row is the same number you would see on the provider bill — never an inflated gross.

For live monitoring, the daemon exposes a Prometheus-compatible /metrics endpoint (token savings, cache hit-rate, latency) guarded by LEAN_CTX_SCRAPE_TOKEN, plus an agentless Datadog push:

curl -H "Authorization: Bearer $LEAN_CTX_SCRAPE_TOKEN" localhost:3333/metrics

Wire it into Datadog, Prometheus/Grafana or your CloudZero/Vantage showback and the savings ledger becomes a first-class line item — attributed by day, project, agent, model and tool.

13. 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)
Push savings into FinOps / cost tooling	finops export (§12)
Live metrics in Datadog / Prometheus	/metrics (§12)

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