Context gauge

In review

Live · web

Context gauge: drag usage past 60% then 85% and watch both forms recolor

Context window

Local Engine · managed

82K / 200K · 41%healthy

0200K

healthy < 60% elevated 60 to 85% critical ≥ 85%

Token budget

ring

82K / 200Khealthy

Usage82K / 200K · 41%

41%

−10%+10%

Inline chip strip: the per-session underline (cyan → amber → red); an unmanaged Cloud Agent session shows a faint empty track, never a faked line

primarygatewayauditdocs

Thresholds 0.60 / 0.85 + the band fills are all var(--token). Cyan is healthy, warm is status; the fill grows, the color hard-cuts (never tweens). The island is live.

Code

TypeScriptKotlinSwift

// Web: React, consuming @dizyx/nockerl-tokens. (Web is the laggard platform. Spec + live demo,
// not yet exported from @dizyx/nockerl-react; promotion is tracked.)

// Linear bar + ring share one threshold model (0.60 / 0.85) and the same
// formatTokenCount readout ("82K / 200K · 41%"). Cyan = healthy, warm = status.
export function SessionContext({ tokens, contextWindow }: ContextState) {
  return (
    <>
      <ContextGauge form="bar" used={tokens} total={contextWindow} />
      <ContextGauge form="ring" used={tokens} total={contextWindow} />
    </>
  );
}

// Compact inline form for a session chips bar. An unmanaged (Cloud Agent)
// session passes used={null} → a faint empty track, never a faked fill.
<ContextGauge form="chip" used={null} total={contextWindow} label="docs" />

// Android: Jetpack Compose (canonical). The gauge ships as the per-chip context
// line under each session keycap: com.nockerl.app.chat.ui.SessionChipsBar.
// Thresholds live in that file as CONTEXT_LOW_THRESHOLD (0.60f) /
// CONTEXT_HIGH_THRESHOLD (0.85f): cyan (< .60, the harness accent) → yellow
// (< .85) → red (>= .85) over a faint canvasEdge track. NO number, just the line.
SessionChipsBar(
    sessions = sessions,
    activeSessionSlug = activeSlug,
    onSessionSelect = viewModel::selectSession,
    onCreateSession = viewModel::createSession,
    // … long-press menu callbacks …
    streamStates = streamStates,
    // per-slug usage ratio (0..1). A slug ABSENT from the map = no data →
    // empty track (shouldShowContextGauge gates this to managed sessions only).
    contextRatios = contextRatios,
    engineAccent = harnessAccent,
)

// The numeric readout is composed from the gateway's ContextUsage:
// utilizationPercent = totalTokens / contextWindow * 100  (SessionConfig.kt),
// formatted with formatTokenCount (ChatUtils.kt): "${used}K / ${total}K · $pct%".
val pct = contextUsage.utilizationPercent.toInt()
val line = "${formatTokenCount(contextUsage.totalTokens)} / " +
    "${formatTokenCount(contextUsage.contextWindow)} · $pct%"

// macOS: SwiftUI (Nockerl Voice). NOT YET SHIPPED. Voice has no context gauge
// (it surfaces no token budget today). This is the intended API, designed from
// the laws + the Android thresholds; see the drift note below.
ContextGauge(used: state.tokens, total: state.contextWindow, form: .bar)
ContextGauge(used: state.tokens, total: state.contextWindow, form: .ring)

// Same band model as Android: < 0.60 accent (healthy) · < 0.85 .warning ·
// >= 0.85 .error. Readout uses the shared formatTokenCount → "82K / 200K · 41%".

Parameters

TypeScriptKotlinSwift

Prop	Type	Default	Description
used *	number | null	n/a	Tokens consumed. null = unmanaged session (no data) → a faint empty track, never a faked fill.
total *	number	n/a	Context-window capacity in tokens. Defaults to 200_000 upstream when the gateway omits it.
form	'bar' | 'ring' | 'chip'	'bar'	Linear meter, ring/arc gauge, or the compact inline chip underline.
label	string	n/a	Optional name shown on the chip form (the session slug).
lowThreshold	number	0.60	Ratio below which the fill is cyan (healthy). Matches Android CONTEXT_LOW_THRESHOLD.
highThreshold	number	0.85	Ratio at/above which the fill is red (critical); between the two it is amber. Matches CONTEXT_HIGH_THRESHOLD.

The gauge is not a standalone composable: it is the context line rendered inside SessionChipsBar. These are the relevant SessionChipsBar parameters; the thresholds + colors are file-level constants in the same file.

Parameter	Type	Default	Description
sessions *	List<SubSession>	n/a	The sub-sessions rendered as keycap chips; each carries its own context line.
activeSessionSlug *	String	n/a	The selected sub-session slug (drives the lifted/brighter keycap).
contextRatios	Map<String, Float>	emptyMap()	Per-slug usage fraction (0..1). A slug absent from the map has no data → empty track (never faked).
engineAccent	Color?	null	Accent used for the LOW (healthy) band, the harness accent. Falls back to accentPrimary (cyan).
streamStates	Map<String, StreamState>	emptyMap()	Per-slug stream state for the leading status dot (unrelated to the context line).

Not shipped in Nockerl Voice. This is the intended SwiftUI API (a View initialized with the usage figures), designed from the laws + the Android thresholds so it round-trips with the other platforms when it lands.

Style	Type	Default	Description
used *	Int?	n/a	Tokens consumed. nil = unmanaged → empty track.
total *	Int	n/a	Context-window capacity in tokens.
form	ContextGauge.Form	.bar	Linear bar, .ring arc, or .chip inline underline.

Cross-platform drift (tracked for reconciliation)

• Swift: Nockerl Voice has no context gauge today (no token budget surfaced). The Swift API above is intended, not shipped.
• Token formatting: Android formatTokenCount is integer-only (1M, 42K, 512); there is no 1.2M decimal form anywhere in the source, so the readout shows 82K / 200K · 41%, never 82.0K. The web demo mirrors this exactly.
• Numeric readout: Android draws the chip line with no number (just the colored line); the used / total · pct% readout lives above the chat input, not on the chip. The web bar/ring forms surface the figure inline.