Agent Read Heatmap

VS Code and Cursor extension that shows which files and lines your agent has read.

• Lines the agent read get a purple background, strongest on the most read lines of that file.
• Files the agent read get a purple label in the Explorer and a badge with the number of reads. The most read file is the brightest.
• Folders carry a badge for how many files were read inside them, however deep, so a collapsed folder still shows the agent has been in there. Folder labels keep their normal colour, and the tooltip has the reads.
• Add a lap to see only the reads from that moment on, like a lap on a stopwatch.

Supported agents

• Claude Code
• GitHub Copilot CLI

Setup

1. Open the command palette and search for Heatmap: Configure.
2. Pick your agent, then one of its sessions. Sessions are listed newest first, by name. The same step takes a session ID, if you know it.
3. Open a file the agent has read. Highlights appear and keep updating while the agent works.
4. Open the Heatmap view in the Explorer sidebar for the buttons and the mini heatmap.

A session that has not started yet has no entry in the list. Pick its agent, paste the ID, and the extension waits for that agent to create it. Claude Code shows the ID with /status; Copilot CLI prints copilot --resume=<id> when a run ends.

Commands

A badge holds two characters, so past 99 the count is shortened: 1h is 100 to 199, 8h is 800 to 899, 2k is 2000 to 2999. Hovering gives the exact numbers: 3 reads on a file, 8 files, 137 reads on a folder.

Heatmap view

The Heatmap view sits in the Explorer sidebar, next to Outline and Timeline.

• Buttons for Toggle, Add lap and Remove lap, with the current lap number next to them.
• A status line with the file name and how much of the file the agent has read, or the session's name when no file is open. Click the session name to change session.
• An Agents list: the session and, nested under it, the subagents it spawned, each with its read count, or with how much of the open file it read. Untick an agent to leave its reads out everywhere. Untick the main session and tick one subagent to see only what that subagent read.
• A mini heatmap of the active file. The whole file fits the view. Read lines are purple bars, wider and stronger the more often they were read. Small line numbers mark key lines. Click or drag to take the editor to that line. It works the other way too: the line under the cursor in the editor is marked on the map, and the status line shows how many times that line was read.

How it works

Both agents write every tool call to a log file as they work: Claude Code a transcript per session, Copilot CLI an event log per session. The extension polls that file, and the transcripts of any subagents, and turns each file-reading call into a line range. Nothing leaves your machine.

The purple is spread over the read counts in use, not over fixed steps. The faintest is the least read line of the file, the strongest the most read, so a file read 30 to 1000 times shows the same spread as one read once or twice. Explorer labels work the same way across the session's files. Lines and files read the same number of times share the faintest colour, because there is nothing to tell apart.

While the heatmap is on, the Explorer decorations that would cover it are switched off in your settings: git.decorations.enabled and problems.decorations.enabled. VS Code ranks a file's problem above anything an extension can colour, so a file with an error in it would be red rather than purple. Toggling the heatmap off puts both settings back as they were. Ignored files keep their muted colour, and problems still show everywhere else.

Colours can be changed in workbench.colorCustomizations: heatmap.file.low, heatmap.file.medium and heatmap.file.high. Settings: heatmap.claudeDir and heatmap.copilotDir point at agent directories other than ~/.claude and ~/.copilot, and heatmap.pollIntervalMs sets how often the log is polled.

Detection sources

From either agent:

• Shell commands that print file content: cat, head, tail, sed -n 'A,Bp', awk with NR ranges, nl, tac, jq, git blame, less, more, bat, and < file redirects.
• Pipes into head, tail and sed -n, which narrow a read. Pipes into wc or checksums, which drop it.
• grep -n and rg -n, which count the lines they print.
• Unified diffs in any shell output, such as git diff, git show and diff -u, which count the lines of each hunk.
• Paths that go through symlinks, on both sides.

From Claude Code:

• The Read tool, with its line offset and limit.
• The Grep tool in content mode: every matched line, context lines included.
• Subagents, including subagents spawned by subagents.

From Copilot CLI:

• The view tool, with its line range. Without a range the whole file counts as read. Listing a directory counts as nothing.
• The grep tool in content mode: every matched line, context lines included.
• Subagents from the task tool, including subagents they spawn themselves.

Detection limitations

• Reads inside other programs: scripts, test runners, linters, builds, xargs, loops over variables.
• grep without -n, which counts as a whole-file read because the matched lines cannot be placed.
• MCP file tools.
• Files attached to a prompt with @file, and files the agent loads on its own, such as CLAUDE.md or AGENTS.md.
• Sessions other than the one being followed.
• Highlights use the line numbers from the time of the read. Editing the file afterwards does not move them.
• Copilot CLI records its working directory once per session, so a cd in an earlier command does not move the paths of later ones. Claude Code records it per command.
• In Cursor, the extension follows agents running in the terminal, not Cursor's own agent.