google-gemini / google-gemini/gemini-cli
Feature: /stats heatmap — calendar heatmap of daily token usage
- Dominant language
- TypeScript
- Stars
- 107k
- Forks
- 14.6k
- Avg merge
- 2d 3h
- Merged PRs (30d)
- 45
Description
### What would you like to be added?
A `/stats heatmap` subcommand (also reachable as `/usage heatmap`, since `/stats` already aliases to `usage`) that renders a GitHub-contributions-style calendar heatmap of daily token usage in the terminal, plus current and longest usage streaks.
Passing a day — `/stats heatmap today`, `/stats heatmap yesterday`, `/stats heatmap 2026-09-10` — would also print that day's breakdown: total tokens, input/output/cached split, session and turn counts, and a per-model split.
Rough shape:
```
Token Usage Heatmap
Mar Apr May Jun Jul Aug Sep
■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■
Mon ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■
■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■
Wed ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■
■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■
Fri ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■
■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■ ■
Less ■ ■ ■ ■ ■ More
844,713 tokens over the last 196 days
Current streak: 4 days · Longest streak: 11 days
```
### Why is this needed?
`/stats` currently reports only the active session, from `uiTelemetryService`, which is in-memory and lost on exit. There's no way to see usage over time — whether today is unusually heavy, which days were expensive, or how consumption trends across a week or month. That's useful for anyone working against a quota or a paid tier.
Worth noting this needs no new storage or telemetry: `ChatRecordingService` already persists every turn to JSONL with a timestamp, model, and token counts, so this is a read-only aggregation over data that's already on disk. Nothing new gets recorded, and nothing leaves the machine.
### Additional context
Two design questions I'd value maintainer input on before writing code:
1. Command output is scrollback, so a history item can't capture arrow keys for interactive hover without fighting the composer. I'd start with the argument-based day lookup above; a focus-taking dialog (like `/theme`) could be a follow-up PR. Any preference?
2. The semantic theme exposes named colors rather than a shade ramp, so intensity levels would map onto existing tokens (`ui.dark` → `ui.comment` → `status.warning` → `text.accent` → `status.success`) unless you'd prefer proper ramp tokens added.
I'd like to implement this and would be happy to have it assigned to me, if you're open to the feature.
Contributor guide
Research direction
Start by tracing the existing `/stats` and `/usage` command entry points, then read `uiTelemetryService` and `ChatRecordingService` to understand current usage reporting and JSONL records. Define the heatmap and day-lookup behavior, including streaks and model breakdowns, and confirm the two design questions with maintainers before implementation. Done means terminal output supports the requested history and daily details without adding storage or telemetry.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- cli, data
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100