Context Gauge

The context gauge is a thin fill bar in the title bar of a Claude Code tile. It answers one question at a glance: how close is this agent to running out of context? It is the signal you would otherwise only get after the fact, when the agent suddenly compacts or truncates mid-task.

Watch the gauge when an agent has been running a long task. As it climbs from green into amber and then red, you know it is time to either wind down the turn, start a fresh session, or hand off to a new agent before context pressure forces a degraded result.

What you can do with it

• See how full the context window is at a glance — the fill bar and percentage label in the tile's title bar.
• Spot trouble early — the bar turns amber at 70% and red at 90%, so you know before the agent hits the wall.
• Read the exact numbers on hover — the tooltip shows the token count and the model's context window size, for example Context ~42% · 84k of 200k tokens (claude-opus-4-7).
• Track Dynamic Workflows separately — when a tile is running a Claude Code Dynamic Workflow, the tooltip adds an aggregated workflow … tokens figure (and an (active) marker while subagents are still running), tracked separately from the main percentage so it does not misrepresent how full the main session is.

How to use it

1. Spawn or open a Claude Code agent tile. The gauge appears in its title bar automatically — you do not need to enable anything.
2. Glance at the color while the agent works:

   Range	Color
   < 70%	Green
   70–89%	Amber
   ≥ 90%	Red

3. Hover the gauge for the exact token count and model.
4. When the gauge climbs into amber or red, decide whether to wrap up the current turn, start a fresh session, or move the work to a new agent.

The gauge only renders for tiles where the detected agent is Claude Code and an agent has actually been detected. It does not appear for Codex, Amp, OpenCode, or a plain shell — those CLIs do not expose a local, structured usage block the way Claude Code does.

Common use cases

• "Is this long refactor about to compact?" — watch the gauge; if it is red, wrap up the turn or start a new session before context pressure degrades the result.
• "How much headroom does the agent have for the next instruction?" — hover for the exact percentage and token count.
• "Is the workflow's subagent burn showing up?" — hover the gauge on a tile running a Dynamic Workflow; the workflow token figure appears separately from the main percentage.

Tips and best practices

• Treat amber as "wrap up soon" and red as "decide now". The agent will keep working past red, but quality can degrade as context pressure rises.
• The gauge pauses while the MadoHub window is backgrounded and refreshes immediately when you switch back, so the reading is always current when you are looking at it.
• If a poll fails transiently (most commonly because no session file exists yet), the gauge keeps showing its last known reading instead of blanking out — do not panic over a brief miss.
• Workflow subagents run in their own contexts, not the main session's window, so their token usage is tracked separately and deliberately not folded into the main percentage.

Related features

• Fleet — see workflow progress (workflow · 3/5 agents) per row alongside state.
• Dynamic Workflows — the Claude Code feature whose subagent token usage the tooltip surfaces.
• MadoAgent — start a fresh agent when one tile is running out of context.

Limitations

• Claude Code only. The gauge does not render for other agent types or plain shells.
• The percentage is an approximation based on the most recent assistant message's usage block, not a live OS-level count.
• Unrecognized model strings fall back to a 200,000-token context window as a conservative default, so the percentage for a brand-new model may be slightly off until MadoHub's table is updated.