terminal delight
Install

Usage and vitals

Brief

At the foot of the left bar, each AI subscription you use gets a row: Claude Code, Codex, Fireworks. A solid rail is the long window, usually the week. A notched rail is the short one, usually five hours. The number is how much of the week is left.

Terminal Delight doesn't measure this itself. A small collector for each vendor asks it and writes down the answer, and the rows read what was written. When there's no answer (no collector, an expired sign-in, a window that vendor doesn't have) the rail is hatched and the number reads —. It never reads 0%, because an empty bar would tell you that you've run out.

Click a row, or press Ctrl+Shift+U, for the usage card: every limit with when it resets, today's use, the last seven days, and which models it went to. Each agent's own health is on the agent wall.

Technical has the collectors, the record format and how a reading goes stale.

Technical

Readings

Where the numbers come from#

One JSON record per subscription, read from two folders; if both have the same subscription, the newer record wins:

  • ~/.local/state/omarchy/agents/usage/, where Omarchy's own collectors write
  • ~/.local/state/terminal-delight/agents/usage/, where Terminal Delight writes

The collectors are Omarchy's scripts, included unedited and built into the binary: claude reads Claude Code's transcripts and Anthropic's usage endpoint, codex asks Codex's app server, fireworks asks Fireworks' billing API. They need python3.

terminal-delight agent-usage update

update runs every collector and writes a record for each that answers; --only claude runs one; list names them; where prints the folders. It exits 1 only if every collector failed. The rows refresh when the window opens, five seconds later, every five minutes after that, and each time the card opens. ↻ refresh on the card runs omarchy-agent-usage-update if you have it, and this binary's own collectors if not.

A row#

mark
The provider's logo from ~/.config/terminal-delight/marks/<id>.svg, drawn in one colour, or two initials.
solid rail
The long window. A limit whose label says week, day or month.
notched rail
The short window, with one notch per unit its label names: five for Session (5-hour). A label with session, hour or current in it.
number
The long window. NN% when fresh, its age (45m, 6h, 2d) when stale, — with no reading. Dropped when the bar is narrower than 190 px.

A limit whose label names neither is placed by order: first short, then long. Rail length shows what's left, or what's spent if you flip the card's bar · what's left chip. Rail colour always shows what's spent: green, amber from 66%, red from 85%. Any use at all draws at least a sliver. Hover a row for the vendor's own names and figures: Weekly (7-day): 41% spent, or …: no reading.

Fresh, stale, unknown#

ReadingWhenDrawn
freshrecent enough for the window it describesNN%
staletrue, but older than the window it describes; a record with no time on it counts as stale, age ?dimmed, with its age
unknownno collector, the collector said it isn't ready, a sign-in has expired, or the vendor has no such windowhatched rail, —

One gap: a limit that arrives with a label but no percent is currently read as 0% spent, so it draws as full rather than unknown (issue 799).

The usage card#

Ctrl+Shift+U, or Ctrl+Shift+Y where an input method takes the U; Σ usage on the agent wall; or a row. At the top is LAUNCH AGENT CONFIG, the launcher's defaults. Then one section per subscription: the vendor's status and what to do about it, each limit as <label> NN% resets in <time>, prepaid balances as left and spent of … funded, and TODAY, LAST 7 DAYS and BY MODEL. With no records yet: nothing collected yet — press refresh, and the folders it looked in.

The record#

{
  "id": "claude",
  "name": "Claude Code",
  "ready": true,
  "limits": [
    { "label": "Session (5-hour)", "percent": 0.23, "resetsAt": "2026-09-25T15:00:00Z" },
    { "label": "Weekly (7-day)", "percent": 0.41, "resetsAt": "2026-09-29T00:00:00Z" }
  ],
  "updatedAt": "2026-09-25T11:02:00Z"
}

id is required. percent is a fraction from 0 to 1, spent. Also read: tierLabel, usageStatusText, authHelpText, balance (remaining, funded, spent, currency, estimated), todayPrompts, todaySessions, todayTotalTokens, recentDays, modelUsage, totalPrompts, totalSessions, activeDays. Anything that can write this file can put a subscription in the bar.

Keepalive#

Earlier builds could type into idle agents on a timer to keep their prompt cache warm. That was removed, along with the AWAY screen that went with it: Terminal Delight never types into a terminal by itself.

Sources

  1. Records, collectors and agent-usage: usage.rs; rails and readings: slot.rs; the card: main.rs.