google-gemini / google-gemini/gemini-cli

Feature: /stats heatmap — calendar heatmap of daily token usage

Open
#29,297 1 comment 0 reactions 0 assignees View on GitHub
area/core effort/medium status/bot-triaged
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.