Context Load Tracking · crystl Docs

Context Load Tracking in Crystl

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:

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

As soon as Crystl detects an agent in a shard, a turns readout appears at the end of the shard status band, the line of text under the terminal. It is the underlined part of that line. It starts as a plain turns label and switches to the estimate once enough turn data has landed to measure a burn rate:

~12 turns left

The burn rate is the median token growth per turn, so a single outlier turn can’t produce a wild estimate. The number is an estimate of how many additional turns can fit before the agent’s own compaction point (around 80% of the usable window for Claude Code, 90% for Codex), based on the shard’s burn rate 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:

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:

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

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

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:

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:

Disabled rows render with a strikethrough and a zero token count (the real cost stays visible in the tooltip), 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 claw back context window: find the heavy entries, 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:

The sidebar health bars in the quest chat panel are powered by the same TurnMetric data: green above 50% health remaining, yellow between 20 and 50%, red below 20%.

Related Docs