ctxmaster

Visualization layer for tokenmaster, the core context-budget metering and decision engine for LLM applications.

The hero surface is the context gauge: a zone-colored fill bar against the model's effective window with threshold ticks, and ancillary rows for context accounting, capacity provenance, token velocity, projected turns to exhaustion with a conservative bound, zone, reserved output, hidden overhead, and cache prefix. The gauge computes nothing itself; every number comes off tokenmaster's MeterState, and anyone can build an alternative visualizer against the same event stream.

Install

pip install ctxmaster

Quickstart

from tokenmaster import Meter
from ctxmaster import ContextGauge

meter = Meter.for_model("anthropic:claude-haiku-4-5")
gauge = ContextGauge()

gauge.attach(meter)   # prints a fresh gauge on every recorded turn

meter.record({"input_tokens": 48_000, "output_tokens": 1_200})

For an in-place updating display in interactive sessions:

with gauge.live(meter):
    ...  # record turns; the panel updates in place

A runnable demonstration lives at examples/demo_gauge.py in the repository: a simulated agent accelerating from green into critical.

What is in 0.1.2

The terminal gauge with per-turn and live rendering, compatible with Tokenmaster 0.1 and 0.2. Planned next: the advice panel rendering tokenmaster recommendations with their rationale, a CLI, and dashboard surfaces. The npm and crates.io packages of the same name provide the matching raw-ANSI gauge with no dependencies beyond the core.

License

MIT