Context Load Tracking

Updated April 9, 2026

Claude models run with a fixed context window — typically 200k tokens — that has to hold the system prompt, tool definitions, conversation history, and any files the model has read. As a session grows, each new turn costs more tokens than the last, and eventually the model either compacts its history or hits a hard ceiling.

Crystl’s context load tracking watches every Stop hook and records how many tokens a shard has actually burned, then projects how many turns it has left before running out.

What Gets Tracked

Each time Claude finishes a turn in a Crystl shard, the Stop hook fires with a payload that includes the turn’s token usage. Crystl captures two numbers per turn:

  • Input tokens — prompt, history, tools, and file contents sent into the model
  • Output tokens — text, tool calls, and thinking generated by the model

Each Stop appends a TurnMetric to the shard’s session log. Turns are tracked per-shard — every shard inside a gem maintains its own independent history, so a long-running planning shard doesn’t pollute the numbers for a fresh debugging shard next to it.

If a hook payload is missing the tokens: {input_tokens, output_tokens} field — for example on older Claude Code builds — Crystl falls back to parsing the transcript file at transcript_path and pulling usage from the last assistant message. Either way, the metric lands in the same place.

The Status Bar Indicator

Once a shard has accumulated 3 or more turns with real token data, a compact indicator appears in the status bar:

~12 turns left

Three turns is the minimum needed to compute a meaningful burn rate. Before that, the indicator stays hidden so you don’t see wild estimates from a single outlier turn.

The number is an estimate of how many additional turns can fit into the remaining context window, based on the shard’s average tokens per turn so far. A shard that’s been reading large files will show fewer turns left than one doing short exchanges.

The Context Load Panel

Click the indicator in the status bar to open the Context Load Panel — a glass panel showing the full breakdown for the active shard:

  • Per-turn token history chart — a bar or line chart of every recorded turn, stacked by input and output, so you can see where the big jumps came from
  • Input vs output breakdown — totals for the shard, with the split between prompt-side and generation-side tokens
  • Burn rate — average tokens per turn across the shard’s history (the number driving the “turns left” estimate)
  • Model name and context window size — e.g. claude-sonnet-4-6 with a 200k window
  • Estimated turns remaining — the same number shown in the status bar, computed as (window - used) / burnRate

The panel updates live as new turns land.

Model Detection

The context window size depends on which model the shard is actually running against. Crystl reads the model ID out of the transcript (the model field on assistant messages — e.g. claude-sonnet-4-6, claude-opus-4-6) and looks up the corresponding window size.

This means switching models mid-session — for example dropping from Opus down to Haiku — will re-scale the estimate on the next turn, rather than locking you into whichever model the shard started with.

Healer Hero Integration

When Crystl Quest is active and your party includes a Healer, context load tracking feeds directly into the Healer’s job. Healers monitor context usage across every shard in the party and can:

  • Warn you in quest chat when an agent is running low on room
  • Post compressed summaries and handoff notes before a shard hits the wall
  • Surface which hero is closest to full so you can plan rotations

The sidebar health bars in the Quest Chat Panel are powered by the same TurnMetric data — green above 70%, yellow between 50–70%, red below 50%.