Usage

Usage is an accounting of what your coding agents have actually consumed — tokens, estimated cost, and cache savings — plus how much of your plan's rate limits you have left.

Opening It

• The Usage page — the sidebar footer's Usage button (pinned there by default) opens it in the main area, beside the sidebar, so checking spend doesn't take you out of the workspace you were in. While it's open the sidebar footer shows a single ← Back button; it and Escape both return you to where you were.
• /usage in the chat composer opens the same page.
• Settings → Usage — open Settings (Ctrl+,) and pick Usage under Agents. It's the same view with a page title.

The Settings row appears when the Agent Chat GUI is on, which it is by default.

The header holds a Usage / Limits toggle, the period control, a refresh button, and Export CSV. Your choice of view, period, chart metric, and breakdown is remembered on this device.

Where The Numbers Come From

Codemux reads the history files your agent CLIs already keep on disk:

That has three consequences worth internalizing:

• It counts sessions Codemux didn't launch. A claude run in a plain terminal shows up here too. The page says so: "…regardless of which app launched them."
• It is this machine only. Token history isn't fetched from a provider's API, and nothing syncs from your other devices.
• Sessions Codemux ran are not double-counted — live usage events are deliberately discarded in favour of the provider's own history file.

Grok is the exception. It has no local history file to read, so Codemux records the usage Grok reports for each turn as it happens. Only Grok chats run inside Codemux are counted, cost is whatever Grok reports (otherwise the tokens are unpriced), and Grok shows no plan limits.

Scanning is incremental, so a refresh re-reads only what changed.

Period and Refresh

A segmented control picks the window: Today, 7 days (the default), 30 days, or 90 days. It's greyed out on the Limits view, which has no period.

Today buckets by hour across the trailing 24 hours — not the calendar day — so an evening session is still visible at 1am. The longer periods bucket by day. Bucket boundaries follow your local timezone.

The page re-scans provider history every 30 seconds while open; the header subline reads Aug 14 – Aug 21 · live (or refreshing…). The refresh button re-scans provider history before refetching, and re-reads plan limits too. Export CSV downloads codemux-usage-7d.csv.

With nothing in range: "No agent activity in this period."

Overview

Three headline numbers:

Below them, a chart of each provider per bucket — toggle between Est. cost and Tokens. Hovering reads out the bucket and the per-provider figures. The legend names each provider in the period (Claude Code, Codex, Cursor, Grok, OpenCode) with its total.

Two footnotes sit under the chart and are worth taking literally:

API/list-price equivalent · not an invoice

input + output + cache read + cache write

Token composition

A five-cell strip breaking the total apart:

• Processed — everything.
• Cached input, with what share of input it was.
• Uncached input, with the number of cache writes.
• Output, noting reasoning tokens where the provider separates them (Codex and OpenCode do).
• Cache savings — dollars, plus a multiplier like 3.4× vs uncached list price.

Cost and tokens by type

Two part-to-whole bars side by side: Cost by type and Tokens by type, each split into Input, Cache read, Cache write, and Output. They tell different stories — cache reads dominate the tokens and barely register in the cost. The cost split always adds up to the period's total; provider-reported cost for a model with no rates to split it by shows as Unsplit.

Provider Lanes

One expandable row per provider: its logo, name, and plan label (Claude Max, ChatGPT Pro, …) or a plain Provider history when no plan is known.

• Quota meters — up to two bars, 5h and week, with a 5h resets 14:30 note in local time (per-model weekly windows such as opus 40% join the note). The bar shifts tone as it fills: calm, then ember past 60%, then attention past 85%.
• Sparkline of that provider's tokens per bucket.
• Tokens and cost (API equivalent) on the right.
• Expand for per-model rows: model id, 18% of tokens (marked · subagents when subagent work contributed), tokens, cost.

Limits

Switch the header toggle to Limits to see every plan window each provider reports — the answer to "can I keep going?":

• One section per provider (Claude Code and Codex first), with the plan name and when it was checked — labelled may be out of date once the reading is more than 15 minutes old.
• One row per window — 5-hour, Weekly, Weekly · Opus, Weekly · Sonnet, Extra usage, or the provider's own name — showing the % left, a bar, a pace icon, and a resets in 2h 13m countdown.
• The bar's fill is the quota left. A thin vertical line marks how much of the window's time is left — where the fill would sit if you spent evenly. Hover the bar for the exact figures and reset time.
• The pace icon reads ahead of pace (spending faster than the window elapses — highlighted), on pace (within five points), or under pace (headroom left).
• A provider whose read failed shows "Could not read limits: …" rather than silently disappearing.

With nothing to show: "No provider on this machine reports plan limits. Claude Code and Codex report them when signed in with a subscription."

How limits are read

Codemux asks the providers directly, through the same channels a session uses: the Claude CLI's usage request and the Codex app-server's rate-limit read. Neither path touches your credentials directly. Reads happen:

• when the Usage page opens,
• when you press refresh,
• when you switch to Limits and the last reading is more than a minute old.

Each read briefly starts the Claude and Codex CLIs. Running sessions also report limits as they go, and the page shows whichever reading is newest. Readings are held in memory only — never written to disk — so after a restart the page reads them again rather than showing a stale snapshot.

Breakdown

A toggle between Model and Day, plus a Model prices button.

• Model — a flat cross-provider list, most expensive first. A model priced with your own rate is marked your price. Click a model to open its details.
• Day — the same buckets, newest first (Hour on Today), with one cost column per provider, the total, and tokens — so a spike can be traced to whoever caused it.

Beside it, a Cost confidence block: how much was Provider reported, how much Codemux Model priced from its table, how much came from Your prices, how much is Unpriced, and the cache savings.

Model details

Clicking a model opens its own view for the selected period: Cost, Tokens, Per 1M tokens, Cache hit rate, and Sessions; a trend chart (tokens for an unpriced model, since its cost is unknown); and its own cost-by-type and tokens-by-type bars. The footer states the rates it was priced at and where they came from — your price, the provider's reported cost, or Codemux's list-price table — with Set price (for a model with unpriced tokens) or Edit price.

How Cost Is Estimated

Cost is a list-price estimate, not a bill.

Codemux carries a static table of published per-million-token rates — separate figures for input, output, cache reads, and the two cache-write durations — and matches your model ids against it.

• Where a provider reports its own cost (OpenCode and Grok do), that figure is preferred.
• A model Codemux doesn't recognize still contributes tokens, but no cost. Those tokens land in the Unpriced line of Cost confidence and show — instead of a dollar figure, so a new model release quietly deflates the total rather than silently inventing a price. Check that line before trusting the headline number — or set a price yourself (below).
• Codemux matches exact model ids (and their dated snapshots), never a model family — so a newly released version shows up as Unpriced until it's added, rather than borrowing an older model's price.
• Rates are standard, short-context list prices. Long-context, priority-tier, fast-mode, and regional pricing, plus server-side tool fees, aren't modelled.
• When the price table changes, your history is re-priced automatically on the next scan.
• Subscription plans are not modelled at all. If you're on a flat-rate plan, the cost column tells you what the same work would have cost through an API — useful for comparing models, meaningless as a statement of what you owe.

Your own model prices

Set model price takes USD per million tokens for Input, Output, Cache read, and Cache write. Your price replaces the built-in rate for every past and future use of that model on this machine. Open it from a model's details, or from Model prices → Add price for a model id you type (provider/model-id).

Model prices lists every price you've set, to edit or remove. Prices are applied when usage is read, so removing one — or Use default price in the editor — restores the original figures. They're stored on this machine only, and the CSV export uses them too.

CSV Export

One row per bucket × provider × model:

bucket_start, provider, model, input_tokens, output_tokens,
cache_read_tokens, cache_write_tokens, reasoning_tokens,
total_tokens, cost_usd, cost_source

cost_source reads override for rows priced with your own rate. Live quota figures are deliberately excluded — they're a point-in-time reading, not history. Export is unavailable on the Limits view.

Related

• Settings — the rest of the settings surface
• Agent Chat — the context-window meter for a single thread