Docs / Commands
gain, dashboard and receipt
Updated
These commands show what Tokenade saved. gain is the quick terminal view, dashboard is the full local report, and receipt turns the totals into a signed, tamper-evident record. All three read the same local ledger, ~/.tokenade/gain.jsonl, and none of them contacts the network.
How each number is computed is explained in how savings are measured.
gain
| Flag | Effect |
|---|---|
| (none) | Totals, then one row per compactor (by op:) |
--json | Structured output. Top level: version, operations, before, after, saved, percent; arrays by_op[] and by_source[] with before, after, count, saved, percent |
--history | Also print one row per ledger entry, for spot checks |
--by-source | Add a by source: section (hook, cli, wrap, …) |
─── tokenade gain (everything recorded: 133 days, since 2026-05-28) ───
operations: 77893
tokens: 679170720 → 48388143
saved: 630782577 (92.9%)
metered: 630600815 (77861 events) is what the server's ingest counts — …
est.: 864678 more where the input WAS measured but the alternative is assumed (skeleton/query/map — …)
both excluded from `saved:` and from `operations:` above …
by op:
auto-compact 2273× −91%
auto:accesslog 1× −99%
…
Read the lines like this:
saved:is measured: real before and after token counts of what Tokenade changed.metered:is what tokenade.net counts toward your plan. It deduplicates more coarsely, sosaved:can be slightly higher.est.:lines are estimates (code intelligence, where the alternative you avoided is assumed). They are kept out ofsaved:.
dashboard
Aliases: dash, stats. With no flag it writes ~/.tokenade/dashboard.html and opens it in your browser. The page is a static local file: a period selector that drives every panel, drill-down by function, layer, agent, project and model, a with/without-Tokenade comparison, and an "outside tokenade" tab showing agent traffic Tokenade did not touch. No server, no requests, no telemetry.
| Flag | Effect |
|---|---|
--text | Print the terminal report instead. The only mode that accepts --days |
--no-open | Write the page and print its path, without opening a browser |
--html [<path>] | Write only the page, to <path> or the default location |
--json | Structured output: operations, tokens_before/after/saved, savings_pct, cache_hits/misses/hit_rate, by_layer[], per_op[] |
--watch [<secs>] | Re-render the text report every <secs> seconds (default 2, 1 to 3600). Ctrl-C to exit. Not combinable with --html or --json |
Over SSH or without a display, the terminal report is printed automatically. Its sections:
| Section | Shows |
|---|---|
| Hero | Tokens saved, percent and operation count for the period |
| TOP COMPACTORS | Measured savings per compactor |
| BY LAYER | The same savings grouped: shell, file-read, content-auto, web, wrapped-mcp |
| WRAPPED MCPs | Third-party MCP servers routed through Tokenade (only when there is such traffic) |
| PROJECTS | Totals per project |
| CODE INTELLIGENCE | Heuristic estimates for skeleton, query, map, impact, semantic |
| AGENT TOKENS | What your agent consumed outside Tokenade, read from its local transcripts |
| INDEX & CACHE | Dedup cache hit rate and semantic index size |
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
24.3M measured · 85.6% · 6439 ops
last 30 days · lifetime saved: 631.9M
+ 759.5k estimated (code-intelligence heuristic)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
── TOP COMPACTORS ──────────────────────────────────────────
html-to-markdown ██████████████████████████████ 127× saved 6.1M 92.4%
auto-compact █████████████████░░░░░░░░░░░░░ 380× saved 3.4M 90.3%
…
── BY LAYER ────────────────────────────────────────────────
web ███████████████████░░░░░░░░░░░ 234× saved 6.3M 91.3%
shell ████████████░░░░░░░░░░░░░░░░░░ 2183× saved 3.9M 88.2%
…
Money figures price each token at the rate of the model that actually ran it.
receipt
Alias: savings-receipt. Aggregates the ledger (events, tokens before, after and saved) and signs it with a key unique to this install, kept in ~/.tokenade/. Use it when you need to hand your savings to someone else in a form they can check.
tokenade savings receipt
────────────────────────
machine …
generated 1791392491 (unix)
version 1.2.2
events 77894
before 679171307 tokens
after 48388476 tokens
saved 630782831 tokens (92.9%)
pubkey …
signature …
tokenade receipt --verify receipt.json # exit 0 intact, 1 tampered
Generating a receipt never contacts the network.
cache-note and mcp-stats
Frames savings with prompt caching in mind. --saved defaults to your lifetime total; --fresh is the share of output that was uncacheable, from 0 to 1 (default 1.0). Savings count most on fresh tool output: a cached re-read is billed at a much lower rate whatever its size.
Rolls up your MCP configuration (servers configured versus wrapped by Tokenade) and the token cost of your skills.
tokenade mcp-stats
MCP manifests: 0 config(s), 0 server(s), 0 wrapped (0%), 0 unwrapped
skills: 0 indexed · eager 0 tok → index 0 tok (saves 0 tok on disclose)
Gotchas
- Every project writes to the same global ledger, so
gainanddashboardshow all projects together. The PROJECTS section splits them. tokenade evict-staleremoves zero-saving noise rows. Run it before a hand-off report if you want clean totals.- The dashboard is local. The figures on your tokenade.net account come from the usage counts described in privacy and data.