Gemini CLI: Daily Token Heatmap With /stats heatmap
Gemini CLI v0.69.0 added a /stats heatmap subcommand that renders a calendar heatmap of daily token usage across local chat sessions. An optional argument (today, yesterday or a YYYY-MM-DD date) drills into a single day. The view helps users see which days and sessions consume the most tokens.
Key Takeaways
/stats heatmapis a new subcommand that draws a calendar heatmap of daily token usage in the terminal.- The data is drawn from local chat sessions, so it reflects the user's own machine activity.
- An optional argument (
today,yesterdayorYYYY-MM-DD) adds a breakdown for a specific day. - It extends
/stats, which previously focused on session and tool-level statistics, with a longer-term view. - A visual history makes it easier to spot usage spikes that affect quota or cost.
- The feature landed in v0.69.0 (stable, 2026-11-19), shipped together with standalone
theme.jsoncustom themes.
A calendar view of your token usage
Gemini CLI v0.69.0, released on November 19, 2026, added a new subcommand to the existing /stats command: /stats heatmap. It shows a calendar heatmap of daily token usage across the user's local chat sessions, so heavy and light days are visible at a glance instead of being buried in per-session numbers.
The release notes describe the feature as a "daily token usage analysis" tool. Until now, /stats offered session-level and tool-level views, such as the tools subcommand that shows tool-specific usage statistics. The heatmap adds a longer time horizon, which is useful for anyone tracking consumption over days or weeks.
Drilling into a single day
The command takes an optional day argument. According to the Gemini CLI command reference, the usage is /stats heatmap [today|yesterday|YYYY-MM-DD]. Running it without an argument shows the calendar view. Passing a day adds a breakdown for that date, which helps explain why a particular square on the calendar is darker than its neighbors.
Why it matters
Token usage maps directly to quota consumption and, on paid plans, cost. A visual history makes it easier to spot spikes, such as a long agentic session or a large-context day, and to adjust habits before hitting limits. Because the data comes from local chat sessions, the view reflects what the user actually ran on their machine.
The feature shipped in v0.69.0 alongside standalone theme.json support for custom themes, and it is available in the stable channel as of November 19, 2026.