Context Load Tracking

Updated May 21, 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 indicator appears reliably once the third turn lands, even on shards where agent detection lagged at session start.

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
  • Per-plugin and per-skill token cost: a list of every installed plugin and skill that gets loaded into the shard’s context, with the token weight of each one

The panel updates live as new turns land.

Plugins and skills breakdown

Below the turn history, the panel itemizes every plugin and skill the shard is currently loading and shows the token cost of each one. Each row is prefixed with a Lucide icon so you can tell entries apart at a glance:

  • file: system prompt and transcript baseline (one row)
  • puzzle: installed plugin
  • wrench: user-level skill

When the active shard’s agent is Claude, crystl scans:

  • ~/.claude/plugins/ for installed Claude Code plugins
  • ~/.claude/skills/ for user-level skills

When the active shard’s agent is Codex, it scans:

  • ~/.codex/plugins/cache/ for Codex plugins
  • ~/.agents/skills/ for shared agent skills

Hover any row to see the plugin or skill’s full description in a native macOS tooltip.

Disabling plugins and skills

Left-click any plugin or skill row to open a small menu below it with options to disable that entry. The available scopes depend on the agent:

Claude rows show two options:

  • Disable for this Gem: writes enabledPlugins.<id>: false (plugins) or skillOverrides.<id>: { enabled: false } (skills) into the gem’s <gem>/.claude/settings.json. The change is scoped to this gem only; other gems keep loading the plugin/skill normally.
  • Disable for all Gems: writes the same flag into your user-level ~/.claude/settings.json. The plugin or skill is then disabled globally for every crystl gem and every other Claude Code session on this machine.

After a Claude disable or re-enable, crystl injects /reload-plugins into the active shard’s running claude session so the change takes effect mid-session. You don’t have to restart Claude.

Codex rows show a single option:

  • Disable Globally (restart codex to apply): Codex has no per-project plugin scope, so disables always land in ~/.codex/config.toml. Codex doesn’t support a hot-reload command, so you’ll need to restart the codex process in that shard for the change to take effect.

Disabled rows render with a strikethrough and reduced opacity so you can tell at a glance which plugins and skills are currently inactive. Click a disabled row and the menu offers Re-enable in place of the disable option.

This view is the fastest way to find the heavy entries when you’re trying to claw back context window: sort by cost, disable the ones you don’t need for the current task, and the next turn’s budget instantly stretches further.

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 and 70%, red below 50%.