Show cached usage details in heatmap headers

[DicksonWu654]

Summary

Show cached usage details in the heatmap header without changing the underlying usage aggregation.

What changed

• keep the main INPUT TOKENS, OUTPUT TOKENS, and TOTAL TOKENS values as the existing totals
• show cache reads as helper text under INPUT TOKENS when present
• show cache writes as helper text under OUTPUT TOKENS when present
• avoid percentage math for cache helpers so providers like Cursor do not imply invalid comparisons
• reserve enough header space so the extra helper lines do not crowd the section layout
• add focused rendering coverage for the cached helper text
• update the README to describe the new header presentation

Why

Cached usage is already tracked in the report data, but it was not surfaced in the rendered heatmap. Showing cache reads and writes directly in the header makes the graph more informative while preserving the existing top-line totals.

Before / After example

Examples below are from one local render against real usage data.

Claude CLI (WSL)

Before:

INPUT TOKENS  460M
OUTPUT TOKENS 16.3M
TOTAL TOKENS  476M

After:

INPUT TOKENS  460M
cache read    459.8M
OUTPUT TOKENS 16.3M
cache write   15.47M
TOTAL TOKENS  476M

Cursor (Windows)

Before:

INPUT TOKENS  997M
OUTPUT TOKENS 9.14M
TOTAL TOKENS  1.01B

After:

INPUT TOKENS  997M
cache read    914.4M
OUTPUT TOKENS 9.14M
cache write   48.2M
TOTAL TOKENS  1.01B

Testing

• added focused SVG rendering coverage for cached helper text
• ran targeted local renderer checks against real report data

Notes

This PR is intentionally scoped to the cached usage display only.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2cc9a76b01

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Avoid reporting 0% when cached tokens exist without base tokens

The new cache helper can show an incorrect percentage because formatPercent hard-codes "0%" whenever the denominator is <= 0. In practice, Cursor rows can have non-zero cache writes while output is zero (packages/cli/src/lib/cursor.ts uses cache.output from Input (w/ Cache Write) but keeps output separate), so the header will render values like write 123 (0%), which misstates the cached share rather than indicating an undefined ratio.

Useful? React with 👍 / 👎.

[cubic-dev-ai]

1 issue found across 3 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/cli/src/graph.ts">

<violation number="1" location="packages/cli/src/graph.ts:277">
P2: `formatPercent` returns `"0%"` when the denominator is zero, but the caller can reach this path with a non-zero numerator (e.g. cache writes present while `output` totals to 0). This renders a label like `write 123 (0%)` which misstates the cached share. Return a fallback like `"—"` or omit the percentage when the ratio is undefined.</violation>
</file>

---

Since this is your first cubic review, here's how it works:

• cubic automatically reviews your code and comments on bugs and improvements
• Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
• Add one-off context when rerunning by tagging @cubic-dev-ai with guidance or docs links (including llms.txt)
• Ask questions if you need clarification on any suggestion

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/cli/src/graph.ts">

<violation number="1" location="packages/cli/src/graph.ts:640">
P2: `cache write` is pinned to row 2 even when row 1 is absent, causing a blank helper line for write-only cache data.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[DicksonWu654]

Before and after: