Skip to content
Back

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-meter
MCP
Dioxus
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-meter
Rust
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.

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

PropTypeDefaultDescription
viewrequiredContextView—Frame from `ContextMeter::view`.
usagerequiredContextUsage—The usage report (breakdown and grid).
variantString"ring"`ring` · `ring-segmented` · `bar` · `grid` · `text` · `card`.
openboolDefault::default()Breakdown popover open.
modelStringDefault::default()Model name for the popover header.
on_toggleEventHandler<()>—Chip pressed.
on_compactEventHandler<()>—"Compact now".

Read from the Rust signature and doc comments.

Keyboard interactions

KeyAction
EnterorSpaceOpen the breakdown
EscClose 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: meter role (or progressbar where meter is unsupported) inside a button that 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 Overflow when 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-segmented draws each category as its own arc with 1 px gaps.
  • Bar: 4 px tall, 48–96 px wide, radius 2 px; bar-segmented shows categories.
  • Grid: cells of window / cells tokens: 10 × 10 for windows ≤ 200K, 20 × 10 for 1M (the Claude Code /context layout, 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 Warning the ring does one scale pulse 1 → 1.12 → 1; on Critical it 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
TransitionDurationDelayEasing / springNotes
Tooltip120 ms fade400 msease-out—
Popover open / close~200 ms / 120 ms0spring 380 / 32 / ease-inshared composer popover
Live sample rate250 ms (≤ 4 Hz)——numbers only; arc interpolates continuously
Arc / bar tween to sample~300 ms0critically damped spring (stiffness 170, damping 26)—
Digit roll (popover)560 ms0cubic-bezier(0.22, 1, 0.36, 1)[research 08 §1.5, MIT]
Digit roll (chip)320 ms0cubic-bezier(0.22, 1, 0.36, 1)—
Turn-end reconcile roll400 ms0cubic-bezier(0.22, 1, 0.36, 1)≈ fades out 120 ms
Grid cell fill120 ms each12 ms stagger, cap 160 msease-out—
Threshold colour240 ms0ease-in-out—
Warning pulse360 ms0spring 400 / 18once
Critical breathe2.4 s loop0sine, opacity 1 ↔ 0.75shared clock; pauses when unfocused
Compact chip unfold200 ms0ease-outsame as queued chip
Compacting sweep1.2 s per turn0linear—
Compacted drain600 ms0cubic-bezier(0.22, 1, 0.36, 1)—
Delta float "−84K"900 ms (rise 8 px + fade)100 msease-out—
Category hover highlight120 ms0ease-out—
Reduced motionvalues 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 Overflow because the new model is smaller sets the model picker's Incompatible reason (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: text or bar variant; 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: Stale after 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: Live overlay 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 ContextMeterChip from oxyn_dioxus and include COMPOSER_CSS plus the token stylesheet once.
  • A GPUI version exists: ContextMeterEl in oxyn_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.

Guides

Oxyn · 74 free components · 264 Pro components · 96 screens · 20 blocks · Dioxus and GPUI