# gain, dashboard and receipt

> See how many tokens Tokenade saved you: gain prints totals in the terminal, dashboard opens a local web report, receipt signs the figures.

Source: https://tokenade.net/en/docs/gain-dashboard-receipt · Updated: 2026-10-16

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](https://tokenade.net/en/docs/savings-measurement).

## gain

```text
tokenade gain [--json | --history] [--by-source] [--recent]
```

| 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 |
| `--recent` | Only the last 7 days of the ledger |
| `--by-source` | Add a `by source:` section (hook, cli, wrap, …) |

```text
$ tokenade gain
─── tokenade gain (everything recorded: 133 days, since 2026-05-28) ───
operations: 77893
tokens: 679170720 → 48388143
saved:   630782577 (92.9%)
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.
- `of which:` (shown only when it applies) is the share of `saved:` credited at a delivery cap: payloads the agent would have refused outright rather than truncated. It stays in the total and is labelled.
- `est.:` lines are estimates (code intelligence, where the alternative you avoided is assumed). They are kept out of `saved:`.

## dashboard

```text
tokenade dashboard [--text | --no-open | --html [<path>] | --json | --watch [<secs>]]
```

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.

| Flag | Effect |
| --- | --- |
| `--text` | Print the terminal report instead. Accepts `--days N` (default 30), like `--watch`; the page has its own period selector |
| `--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 |

```text
$ tokenade dashboard --text
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   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

```text
tokenade receipt [--json] [--verify <file>]
```

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.

```text
$ tokenade receipt
tokenade savings receipt
────────────────────────
machine     …
generated   1791392491 (unix)
version     2.0.1
events      77894
before      679171307 tokens
after       48388476 tokens
saved       630782831 tokens (92.9%)
pubkey      …
signature   …
```

```bash
tokenade receipt --json > receipt.json
tokenade receipt --verify receipt.json   # exit 0 intact, 1 tampered
```

Generating a receipt never contacts the network.

## cache-note and mcp-stats

```text
tokenade cache-note [--saved N] [--fresh F]
```

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.

```text
tokenade mcp-stats [--json]
```

Rolls up your MCP configuration (servers configured versus wrapped by Tokenade) and the token cost of your skills.

```text
$ tokenade mcp-stats
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 `gain` and `dashboard` show all projects together. The PROJECTS section splits them.
- [`tokenade evict-stale`](https://tokenade.net/en/docs/maintenance) removes zero-saving noise rows. Run it before a hand-off report if you want clean totals.
- The dashboard is local, like `gain` and the status line: every figure is computed on your machine from your local ledger, and nothing is sent anywhere. See [privacy and data](https://tokenade.net/en/docs/privacy-telemetry).

## Related

- [How savings are measured](https://tokenade.net/en/docs/savings-measurement)
- [Output compaction and the stash](https://tokenade.net/en/docs/compaction)
- [style and statusline](https://tokenade.net/en/docs/style-statusline)
- [Privacy and data](https://tokenade.net/en/docs/privacy-telemetry)
