Context meter
How full the context window is: a ring, a segmented ring, a bar, a grid, text or a card, warning and critical levels, and a breakdown by system, tools, files and history.
oxyn add context-meterDioxus
let mut meter = use_signal(ContextMeter::default);
let view = meter.write().view(&usage, clock.now()); // eases between reports
rsx! {
ContextMeterChip {
view: view,
usage: usage.clone(),
model: "Claude Haiku 5",
on_compact: move |_| agent.compact(),
}
}Rendered from Rust at build time · goes live when visible
When to use
- Long agent sessions fill the model's context window with system prompt, tool schemas, memory files, attachments and history.
- When it fills, quality drops, requests fail or the app compacts.
- The meter sits in the composer row (or status bar) and answers: *how full is it*, *what is filling it*, and *what should I do now* (compact, hand off to a new thread, remove a tool server, drop an attachment).
- It must update live while the agent streams without becoming a distraction, and only raise its voice at thresholds.
When not to use
- The model menu of an AI chat: use Model Picker instead.
- Prompt composer with model picker, voice input, app connections and approval request: use Chat Composer instead.
- The prompt box for an agent, in six layouts: use Composer instead.
Installation
Context meter is free and MIT. The oxyn CLI copies its code, and the components it needs, into src/oxyn/ of your Dioxus or GPUI project, so it is yours to change.
Terminal
cargo install --git https://github.com/ismailqureshi72/Oxyn oxyn-cli
oxyn init
oxyn add context-meterRust
use crate::oxyn::{ContextMeterChip, COMPOSER_CSS};Rather depend on the crate? cargo add oxyn-dioxus oxyn-core --git https://github.com/ismailqureshi72/Oxyn, then use oxyn_dioxus::{ContextMeterChip, COMPOSER_CSS};
Usage
Dioxus · rust
let mut meter = use_signal(ContextMeter::default);
let view = meter.write().view(&usage, clock.now()); // eases between reports
rsx! {
ContextMeterChip {
view: view,
usage: usage.clone(),
model: "Claude Haiku 5",
on_compact: move |_| agent.compact(),
}
}Examples
Ring
A ring that fills.
Code
let mut meter = use_signal(ContextMeter::default);
let view = meter.write().view(&usage, clock.now()); // eases between reports
rsx! {
ContextMeterChip {
view: view,
usage: usage.clone(),
model: "Claude Haiku 5",
on_compact: move |_| agent.compact(),
}
}Critical
Nearly full; compact suggested.
Code
let mut meter = use_signal(ContextMeter::default);
let view = meter.write().view(&usage, clock.now()); // eases between reports
rsx! {
ContextMeterChip {
view: view,
usage: usage.clone(),
model: "Claude Haiku 5",
on_compact: move |_| agent.compact(),
}
}Grid
A grid of cells by category.
Code
let mut meter = use_signal(ContextMeter::default);
let view = meter.write().view(&usage, clock.now()); // eases between reports
rsx! {
ContextMeterChip {
view: view,
usage: usage.clone(),
variant: "grid",
model: "Claude Haiku 5",
on_compact: move |_| agent.compact(),
}
}Card
The full breakdown.
165K / 200K tokens83%Claude Haiku 5
System9.2K4.6%
Tools14.6K7.3%
Memory & rules3.1K1.5%
Files & attachments18.4K9.2%
History100K50.0%
Reserved20K10.0%
Other6000.3%
Free34.1K17.0%
Code
let mut meter = use_signal(ContextMeter::default);
let view = meter.write().view(&usage, clock.now()); // eases between reports
rsx! {
ContextMeterChip {
view: view,
usage: usage.clone(),
variant: "card",
model: "Claude Haiku 5",
on_compact: move |_| agent.compact(),
}
}API reference
ContextMeterChip
| Prop | Type | Default | Description |
|---|---|---|---|
viewrequired | ContextView | — | Frame from `ContextMeter::view`. |
usagerequired | ContextUsage | — | The usage report (breakdown and grid). |
variant | String | "ring" | `ring` · `ring-segmented` · `bar` · `grid` · `text` · `card`. |
open | bool | Default::default() | Breakdown popover open. |
model | String | Default::default() | Model name for the popover header. |
on_toggle | EventHandler<()> | — | Chip pressed. |
on_compact | EventHandler<()> | — | "Compact now". |
Read from the Rust signature and doc comments.
Keyboard interactions
| Key | Action |
|---|---|
| EnterorSpace | Open the breakdown |
| Esc | Close it |
Accessibility
- A meter inside a button: aria-valuenow, aria-valuemax and a valuetext like "112 thousand of 200 thousand tokens used".
- Crossing warning or critical is announced politely; routine token changes never are.
From the spec
- Chip:
meterrole (orprogressbarwheremeteris unsupported) inside abuttonthat opens the popover;aria-valuemin=0,aria-valuemax=window,aria-valuenow=used,aria-valuetext"112 thousand of 200 thousand tokens used, 56 percent, 88 thousand free" (prefix "about" while estimating). - Labels per state: "Context: 56 percent used. Show breakdown", "Context warning: 74 percent used", "Context critical: 91 percent used. Compact suggested", "Compacting context", "Context compacted, now 28 percent", "Context over limit by 12 thousand tokens, sending is blocked".
- Live region: polite on crossing warn / critical and on compaction done; assertive only for
Overflowwhen it blocks sending. Never announce routine token changes; at most one announcement per 5 s. - Popover: category list is a
list; each row's swatch is decorative; token values are text. - Contrast: warn/critical fills ≥ 3:1 against the track; labels ≥ 4.5:1; daltonized themes swap amber/red for patterns (hatched critical) in addition to hue.
- Focus order: … permission → context → send; compact chip receives focus only when the user tabs to it.
Motion & interaction
- Ring: 16 px diameter in the composer row (20 px in the status bar), stroke 2 px, track at 18 % opacity, round cap; starts at 12 o'clock, clockwise (counter-clockwise in RTL).
ring-segmenteddraws each category as its own arc with 1 px gaps. - Bar: 4 px tall, 48–96 px wide, radius 2 px;
bar-segmentedshows categories. - Grid: cells of
window / cellstokens: 10 × 10 for windows ≤ 200K, 20 × 10 for 1M (the Claude Code/contextlayout, research 05); cell 6 px, gap 2 px in the popover; filled cells coloured in category order (row-major), reserved cells hatched, free cells hollow 1 px outline. On change, cells fill one by one with a 12 ms stagger (cap 160 ms total). - Rolling digits: odometer per digit, tabular figures, top/bottom 18 % mask fade, digits roll up when the value grows and down when it shrinks — after OpenCode AnimatedNumber (560 ms, cubic-bezier(0.22, 1, 0.36, 1)) [research 08 §1.5, MIT]. In the 16 px chip we use 320 ms.
- Live updates while streaming: values are sampled at ≤ 4 Hz (every 250 ms); between samples the arc eases toward the target (critically damped spring) so it never jumps; a count-up adapts its step to the gap — the same idea as Claude Code's adaptive token count-up (+3 / 15 % / +50 per 50 ms tick) [research 08 §1.3, LEAK — behaviour reference only].
- Threshold crossing: colour cross-fades over 240 ms; on entering
Warningthe ring does one scale pulse 1 → 1.12 → 1; onCriticalit starts a slow breathe (the Claude desktop ring "breathes" above 80 % [research 08 §1.4, RE]; our timing is our own). - Compact prompt chip: unfolds upward above the composer (same choreography as queued chips in the send control); composer does not move.
- Compacting: the filled arc sweeps as a 25 % indeterminate segment (1.2 s per turn); grid cells "squeeze" toward the start (history cells collapse into a single summary-coloured block).
- Compacted: fill drains from old to new ratio; the delta label "−84K" rises 8 px and fades; the numbers roll down. A compaction marker is inserted into the transcript (related component).
- Hover in popover: hovering a category row highlights its segment / cells (others dim to 40 %).
- Overflow: a 2 px red notch appears at 12 o'clock; the send control shakes once if the user presses Enter (that shake belongs to the send control spec).
Timing
| Transition | Duration | Delay | Easing / spring | Notes |
|---|---|---|---|---|
| Tooltip | 120 ms fade | 400 ms | ease-out | — |
| Popover open / close | ~200 ms / 120 ms | 0 | spring 380 / 32 / ease-in | shared composer popover |
| Live sample rate | 250 ms (≤ 4 Hz) | — | — | numbers only; arc interpolates continuously |
| Arc / bar tween to sample | ~300 ms | 0 | critically damped spring (stiffness 170, damping 26) | — |
| Digit roll (popover) | 560 ms | 0 | cubic-bezier(0.22, 1, 0.36, 1) | [research 08 §1.5, MIT] |
| Digit roll (chip) | 320 ms | 0 | cubic-bezier(0.22, 1, 0.36, 1) | — |
| Turn-end reconcile roll | 400 ms | 0 | cubic-bezier(0.22, 1, 0.36, 1) | ≈ fades out 120 ms |
| Grid cell fill | 120 ms each | 12 ms stagger, cap 160 ms | ease-out | — |
| Threshold colour | 240 ms | 0 | ease-in-out | — |
| Warning pulse | 360 ms | 0 | spring 400 / 18 | once |
| Critical breathe | 2.4 s loop | 0 | sine, opacity 1 ↔ 0.75 | shared clock; pauses when unfocused |
| Compact chip unfold | 200 ms | 0 | ease-out | same as queued chip |
| Compacting sweep | 1.2 s per turn | 0 | linear | — |
| Compacted drain | 600 ms | 0 | cubic-bezier(0.22, 1, 0.36, 1) | — |
| Delta float "−84K" | 900 ms (rise 8 px + fade) | 100 ms | ease-out | — |
| Category hover highlight | 120 ms | 0 | ease-out | — |
| Reduced motion | values and colours swap instantly (≤ 80 ms opacity); no roll (digits replace), no breathe (static critical colour + "!" glyph), no sweep (static "Compacting…" text), no float (delta shown as text for 2 s) | — | linear | — |
Responsive behaviour
- ring and text fit a toolbar; card is for a side panel.
Edge cases (spec)
- Huge windows (1M+): grid switches to 20 × 10; labels use
1.2M; categories < 0.5 % fold to "Other". - Tiny windows (8K): cells = 8K / 100 = 80 tokens each; fine.
- Unknown window size: show absolute tokens only ("82K tokens"), no ring fill, no thresholds.
- Window changes on model switch: ratio recomputes; the arc tweens; crossing into
Overflowbecause the new model is smaller sets the model picker'sIncompatiblereason (shared data). - Estimates wrong by a lot (e.g. images): the turn-end reconcile may jump > 10 %; roll anyway, no extra emphasis.
- Long category names / many files: rows ellipsis at 1 line; files list caps at 8, then "+12 more".
- RTL: ring direction counter-clockwise, bars fill right-to-left, digits stay LTR.
- Tiny sizes (16–20 px): ring only (no label); thresholds still change colour and add a 4 px dot (amber / red) so colour isn't the only signal.
- Dense IDE panels:
textorbarvariant; popover becomes a side card if vertical space < 240 px. - Touch: tap opens popover as bottom sheet; rows 44 px; remove actions behind swipe or "…" menu.
- Slow networks:
Staleafter 30 s without a usage report while the agent is busy; keep last value. - Very fast agents: many reports in a burst coalesce to the 250 ms sample; at most one threshold announcement per 5 s.
- Very slow agents:
Liveoverlay may last minutes; breathe pauses when the window is unfocused. - Compaction while the popover is open: popover rows animate to new values; actions disabled during
Compacting. - Subagents with their own windows: the meter shows the parent thread only; subagent windows belong to the subagent tree component.
Notes for AI
- Import
ContextMeterChipfromoxyn_dioxusand includeCOMPOSER_CSSplus the token stylesheet once. - A GPUI version exists:
ContextMeterElinoxyn_gpui. - Props to set first:
view,usage. - Keep its states and timings as they ship; restyle it through the CSS variables rather than by hand.