Status line¶

The status line sits under the prompt and answers two questions all the time: how much am I saving, and is my cache about to cost me? It shows nothing in a project that is not routed through the proxy.

The first line is money, the second is the cache clock, the sub-agents, the context bar and at most one hint:

saved $0.31 session · $4.20 today · ★ $212.40 lifetime
cache ● █████░ 3:57 │ agents 2 · soonest ◐ 0:51 │ ctx ███░░░░░ 41%

What each piece means¶

The cache clock¶

The bar drains over the cache's own lifetime: 5 minutes, or 1 hour on the 1 h tier.

Every state¶

Warm: green, seconds ticking down¶

Warm on the 1 h cache tier¶

The bar rescales to the tier's lifetime.

Expiring: amber, with what a pause would cost¶

Critical: red, last 15 seconds, marked !¶

Cold: counts up how long it has been cold¶

Keep-alive ping in place: ↻¶

Sub-agents¶

One running sub-agent, then several (the count and the one expiring soonest), then five.

Model changed while the cache is warm¶

Switching model rewrites the cache, so the hint says so before you send.

Tool set changed¶

From Claude Code's own miss report, when it is under two minutes old.

Proxy offline¶

Refused is cg ✕ proxy offline. A slow proxy shows cg: stats loading…, then the last numbers with ⏳. Hung for ten minutes shows cg? not responding.

Narrow terminals and the worst case¶

At 80 columns, with the cache cold, five sub-agents and a hint:

At 40 columns the line sheds, in order: tools, latency, spend, the update marker, the long hint form, then the agents shrink to a count, then the saved label and the context bar. The cache clock is shortened last.

Layouts¶

Switch without editing settings, and keep the choice across renders:

python3 "<plugin dir>/scripts/statusline.py" --set-layout=detailed   # or minimal, balanced, auto

auto forgets the choice. A remembered layout wins over the flag in the installed command. To change the installed command instead, re-run /context-guru:statusline with --layout=minimal|balanced|detailed. Hide or show single elements with --hide=a,b and --show=a,b (update save spend cache agents ctx hint latency tools ka), or the environment variables CG_STATUSLINE_LAYOUT, CG_STATUSLINE_HIDE, CG_STATUSLINE_SHOW and CG_STATUSLINE_COLUMNS.

Modes¶

Five more layouts each answer one question on the second line, next to the cache clock. Choose one with --layout=<name> in the installed command, or remember it with statusline.py --set-layout=<name> (--set-layout=auto goes back to the default).

All five show the cache clock but have no hint slot.

spark¶

strip¶

At 120 columns:

heat¶

fill¶

With room for the legend (120 columns):

watch¶

These layouts draw with the same renderer as the terminal views. NO_COLOR removes the colour, and CG_ASCII=1 swaps the glyphs for plain characters (o hit, ~ partial, X miss, #, = and - for bars). That ASCII switch exists for these layouts only; the default layouts have none. Their data is cached (series and spend for 2 minutes, requests for 4 seconds) and a render never waits for it.

Refresh and the one-second clock¶

Claude Code redraws the status line on every message and, if you ask, on a timer. The installer writes "refreshInterval": 1 next to the command, so the clock ticks every second (the minimum Claude Code accepts). A value you set yourself is kept when the status line is re-installed, so an install made earlier with a longer interval keeps it. To get the one-second clock on an existing install, set it by hand in the settings file that holds the status line:

"statusLine": { "type": "command", "command": "…", "refreshInterval": 1 }

and start a new session. Older Claude Code versions ignore the key and redraw only on events. The clock is arithmetic on a timestamp the proxy supplies, so a redraw needs no new network read. A render takes about 55 ms warm and 90 ms on a cold cache. The cost is one short process per second per open session. If that matters, set a larger refreshInterval (for example 5); the clock then moves every 5 seconds.

Render time¶

Every layout returns in about 0.4 s at worst, Python start-up included (the slowest run in the table took 0.43 s). The render has a 0.36 s budget. Only the proxy's totals (/api/stats?lean=1) are waited for, and the cache state is read in parallel under the same deadline. Everything else (day and lifetime totals, series, spend, requests) comes from a disk cache that a detached background process refreshes, one per 30 seconds. A timeout shows the last numbers with ⏳, never "proxy offline".

Measured on this host, which is loaded and shared with production: 50 runs per cell, wall milliseconds, median / 95th percentile / maximum. "Slow" is a server that sleeps 5 seconds on every request.

The same harness on the status line before this work:

The slow-proxy case went from about 680 ms to about 390 ms. Healthy renders are about 10 ms slower than before, from the extra elements (agents, spend).

Colour and plain terminals¶

Colours are the basic ANSI set plus dim, so they follow your terminal theme on light and dark backgrounds. NO_COLOR=1 or TERM=dumb removes the colour; the clock, bar and symbols still carry the state. The default layouts have no ASCII mode: their bars and symbols are Unicode (the modes can switch to ASCII with CG_ASCII=1). --layout=minimal keeps to one short line.

Turn it on, off, or change it¶

/context-guru:statusline installs it (the install also does this by default), changes the layout, or turns it off with settings.py off, which restores whatever status line you had before. It never sends a keep-alive ping; it only reads.