ContextClues reads a running Claude Code session on your own machine and shows exactly what is in its context window, what is filling it, and how much working room is left before it compacts.
Nothing is uploaded. Nothing is modified. Every number is labeled with how it was obtained.
git clone https://github.com/MaxwellVolz/contextclues.git && cd contextclues && npm i && npm run dev
Token count is the API's own figure from the last assistant turn (observed). Max window is assumed. Rate observed, runway projected.
| # | Source | Preview | ~Tokens | Age | Status |
|---|---|---|---|---|---|
| #1360 | tool result | [Read] src/billing/invoice.ts | ~4,102 | just now | IN CTX |
| #1359 | assistant | Read({"file_path":"src/billing/… | ~86 | just now | IN CTX |
| #1358 | tool result | [Bash] npm test: 41 passing | ~612 | 8s ago | IN CTX |
| #1357 | user | also update the proration path | ~11 | 22s ago | IN CTX |
| #1356 | assistant | The proration branch assumes a… | ~340 | 31s ago | IN CTX |
| #1355 | tool result | [Grep] "prorate": 18 matches | ~1,204 | 44s ago | IN CTX |
| #1352 | injected | [total_tokens_reminder] | ~13 | 1m ago | IN CTX |
| #1341 | tool result | [Read] package-lock.json | ~31,880 | 14m ago | COMPACTED OUT |
| #1338 | system | compact_boundary: 412k → 96k | · | 14m ago | BOUNDARY |
| #1330 | tool result | [Read] src/db/schema.sql | ~2,910 | 19m ago | COMPACTED OUT |
"Assumed" built-ins come from a static list. Used and deferred entries were observed in this session's transcript.
The full case file. One session, live, on localhost.
A long agent session fills its context window quietly. There is no gauge, no breakdown, and no warning. One accidental read of a lockfile can take a third of the window, and nothing tells you it happened. You are steering a process whose most important state variable is invisible.
When the window fills, the session compacts. Older material is summarized away and dropped. Work you assumed was still in context is gone, and the only signal is the agent starting to behave as if it forgot something. By then you have already paid for it: a repeated explanation, a wrong answer you trusted, a debugging cycle chasing a problem that was never in the code.
ContextClues turns that black box into an instrument panel. It runs beside your session and answers the questions you currently have to guess at: how full is the window, what is taking up the room, what did compaction actually drop, and how long can I keep going.
Claude Code keeps a registry of running sessions and an append only transcript of every event on local disk. ContextClues watches those files, tail parses the transcript incrementally, indexes it into a local database, and streams updates to the dashboard over server sent events. Claude's files are opened read only and are never modified.
It deliberately does not install an agent hook. A hook would give push style events, but installing one edits your configuration, and this tool does not change your setup without being asked.
~/.claude/sessions/*.json ──┐ ┌─ local SQLite ~/.claude/projects/**.jsonl ──┤──► collector ──►──┤ settings, .mcp.json, plugins ──┘ read only └─ event bus ─► SSE ─► dashboard
Every session is a case file. Context entries are evidence. What the tool notices, it files as clues.
Tokens in the window from the API's own count, as a share of maximum, with cache breakdown and observation age.
Growth across every API request, with burn rate, projected runway in time and requests, and compaction boundaries marked.
What is occupying the window, stacked by source: your messages, replies, tool results, injected context, and system overhead.
Every transcript record, searchable, with size, age, whether it is still in context, and why it is believed to be there.
Every known tool with its provider, its status, where that knowledge came from, and how many times it was actually used.
Tool calls, file reads, results, compactions, and tool availability changes, streaming in as they happen.
Oversized results, files read repeatedly, exact compaction drops, unused tools, window pressure, and stale heavy entries.
This tool reads the most sensitive text on your computer: your code, your prompts, and your command output. It is built so that none of it goes anywhere.
No cloud service, no account, no authentication, no telemetry. The dashboard is a localhost page and the process makes no outbound calls.
Claude's session files are opened read only and are never written to. Nothing under your agent's configuration directory is created, edited, or deleted.
API keys, tokens, JWTs, private keys, and secret style environment assignments are detected and scrubbed before any preview is stored or rendered.
The tool's own index lives in a local folder you can delete at any time. It rebuilds itself from the transcripts on next run.
A context dashboard is only useful if you can tell measurement from guesswork. Some of these figures are genuinely knowable and others are not, so nothing is presented as plain fact. Every value carries one of four confidence labels, visible in the interface, so you always know which one you are reading.
The same care goes into the projection. Growth per request is strongly right skewed: most requests add a little, and an occasional large file read adds a lot. Runway is a question about cumulative growth, so the projection is driven by the mean rather than the median, because the mean counts large requests at the rate they actually occur. A median would describe a typical request while systematically under predicting how fast the window fills. The panel reports both, and when the average sits far above the typical request it says the session is spike dominated and widens the runway into a range.
ContextClues never claims access to the model's hidden reasoning, and it does not pretend to know exactly which messages survive between compactions. That is inference, and it is labeled as inference.
Clone it, install it, run it. Then start a Claude Code session in another terminal and it appears automatically.
# requires Node.js 22.5 or newer $ git clone https://github.com/MaxwellVolz/contextclues.git $ cd contextclues $ npm install $ npm run dev → http://localhost:4310
Node.js 22.5+ uses the built in SQLite module, so there is nothing to compile.
A machine where Claude Code has run it reads the session files that are already there.
Live sessions are auto detected marked with a dot, updating in real time as the transcript grows.