Heatmap Claude Code mod: a Claude Code activity heatmap for your sessions

Heatmap is a community mod by Hamza Zafar (hamzafer), part of his claude-code-mods collection. It gives you a Claude Code activity heatmap: a grid like the GitHub contribution graph, built from your own session history. Run /heatmap and a pane opens with one square per day, up to 52 weeks wide depending on the pane width, with the weeks running left to right and Monday to Sunday top to bottom. The darker or brighter the square, the more active minutes that day.

Under the grid it prints a current streak and your best streak, total active time and session count for the weeks shown, and a "peak" line with your busiest weekday and hour. In the all-projects view it also lists your top three projects with a share bar and their time. The p key switches the pane between all projects and the current repo, and q closes it. When a streak reaches 7, 30 or 100 days, a toast says so once.

Active time is a simple rule from the code: the gaps between messages in a session count, unless a gap is longer than five minutes. It is a rough measure of time at the keyboard, not billing or token data. The mod keeps its own daily ledger, so the grid does not shrink when Claude Code cleans up old logs.

Use any of the methods in the install block; they install straight from the author's own marketplace. Restart Claude Code or run /reload-plugins, then run /heatmap. The first time, the pane says it is reading your session history, which takes a few seconds on a large history.

At session.start the mod registers /heatmap and refreshes its ledger in the background, and it refreshes again at session.end. The refresh, from hooks/register.tsx:

const dir = await configDir($)
const file = `${dir}/heatmap/days.jsonl`
const parsed = (await $.fs.exists(file)) ? parseLedger(await $.fs.read(file)) : []
const old = parsed.length > 0 ? parsed : null // an empty or broken ledger backfills again
...
const logs = await readLogs($, `${dir}/projects`, since)
const merged = mergeLedger(old ?? [], aggregate(logs, localOffset, fromDay), fromDay)
await $.fs.write(file, formatLedger(merged))

With no ledger it backfills every day the logs hold. After that it re-reads only logs touched since yesterday, so older days stay as they were. To read a log it runs grep -oE for the "timestamp" fields, and grep -m1 for the first "cwd", so message text is never loaded into the mod. The pure counting rules live in hooks/heat.ts, and the grid itself is a separate surface module, hooks/grid.tsx, drawn with an orange ramp chosen from your saved theme (dark, light, or one that reads on both).

There are no options in /config. The only controls are the p and q keys in the pane and the arrow keys after you click the grid. The pane opens on the all-projects view, which lists your project names; press p to switch to the current repo first if you plan to share a screenshot. To change the look, edit GLYPHS and RAMPS in hooks/grid.tsx, or GAP_MS, MAX_WEEKS and MILESTONES in hooks/heat.ts.

We read every file the plugin can execute before running it: .claude-plugin/plugin.json, hooks/hooks.json, hooks/register.tsx, hooks/heat.ts, hooks/grid.tsx, the type declarations, tsconfig.json and the tests. There is no package.json, install script, bundled or minified code, or binary. Findings:

• Network: none. No fetch, sockets or URLs in the code.
• Processes ($.process.run): grep only, with an argv array, on your session logs: -oE for timestamps (register.tsx:251) and -m1 -oE for the first working directory (:263).
• File writes ($.fs.write): one file, <config dir>/heatmap/days.jsonl (register.tsx:226), inside ~/.claude (or CLAUDE_CONFIG_DIR). It writes nothing to settings.json, shell files, LaunchAgents, cron or git hooks. The ledger holds, per day and project: the project folder name, its display name (the last part of its path), active minutes, sessions and minutes per hour. It does not hold message text.
• Reads: every *.jsonl log under <config dir>/projects, whichever project it belongs to (register.tsx:231-259), and .claude.json for the saved theme only (:179-180).
• Background work: it refreshes on every session start and session end without asking first. That is the mod's whole purpose and it stays on your machine, but you should know the ledger is written as soon as the mod is loaded. No daemons; nothing keeps running after Claude Code exits.
• Environment: CLAUDE_CONFIG_DIR and HOME, used to find the config folder. They are not sent anywhere.
• Telemetry: none.
• Model influence: none. It does not touch prompts or tool results and has no gating hooks.
• External requirements: grep on the path. Nothing else.
• Privacy note: the all-projects view shows names of your projects, drawn from your history. Keep that in mind when you screenshot the pane.
• License: MIT, with a LICENSE file in the repository root.

claude plugin validate reported no errors or warnings on the manifest. Its directory check listed one non-blocking warning, a missing plugin icon. The author's 28 tests (22 for the counting rules, 6 for the mod) passed with claude plugin test on Claude Code 2.1.307.

Checked with Claude Code 2.1.307 on macOS (validate and tests). The pane draws in the terminal or the desktop app. If something looks wrong:

• "Reading your session history…" stays on screen. Close and reopen the pane; if the read failed, the pane prints the reason.
• The grid is empty. The mod only counts logs under <config dir>/projects. A new install has history only from the sessions Claude Code still keeps.
• Keys do nothing. Click the grid once to give it the keyboard; p also works as the hotkey of the scope button.
• Not all weeks fit. The grid takes two columns per week, so a narrow pane shows fewer weeks. In our test terminal the pane was cut off after six grid rows, so the lines below the grid were out of view; we did not find out how to scroll them into view.