# Context Load Tracking

> Monitor per-shard token usage and estimate how many turns remain before Claude runs out of context.

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](/docs/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](/docs/quest-chat) are powered by the same TurnMetric data — green above 70%, yellow between 50–70%, red below 50%.

## Related Docs

- [Gems & Shards](/docs/gems-and-shards) — How shards are organized per project
- [Quest Heroes](/docs/quest-heroes) — Healer role and context monitoring
- [Quest Chat Panel](/docs/quest-chat) — Sidebar health bars backed by TurnMetric data

---
Source: https://crystl.dev/docs/context-load/