I build ccdeck. The step-by-step version of this post is at ccdeck.dev/guides/cost-and-quota.
Three questions I kept asking
With several agent sessions running, I want to know where the tokens went and whether I have enough quota to finish. Those are different questions, so I keep three numbers in view:
- How much quota is left before the 5-hour window cuts me off — and will I hit it before it resets?
- What did this one session cost? The big refactor, or the one that went in circles for an hour.
- Where did this month go? Which days, which models, which projects.
ccdeck answers all three on one page, and is careful to say which number comes from where. This post walks through them.
npx ccdeck
The topbar: this month
The topbar always shows this month: what you have spent since the 1st, in tokens and dollars, across every Claude Code and Codex session on the machine. For the rest, press U (or click Usage).
Demo data. Both CLIs are watched, so both quotas are drawn.
Question 1 — how much quota is left?
Each bar is one quota window:
- Claude quota has a 5-hour window and a 7-day window, plus Sonnet (7d) and Opus (7d) when Anthropic reports them.
- Codex quota has a bar for each window OpenAI reports, with your plan beside the heading.
Under each bar:
- resets in is the time until the window starts again;
- on pace or 4% over pace compares your use with the time gone;
- runs out in means that, at the rate so far, you would reach 100% before the reset;
- used up means the window is full.
A bar turns amber from 70% and red from 90%. The age beside a heading (such as 2m ago) says how old the reading is, and an incident on Claude Code, the Claude API or Codex shows as a line under that quota's heading, linking to the status page.
You need a subscription for this part: Claude Code signed in with a Claude plan, or Codex signed in with codex login and a ChatGPT account. With an API key, or Bedrock or Vertex, there is no quota window — the panel says No quota to show, and your spend still shows.
If you juggle more than one Claude account, the accounts panel shows each account's 5-hour and 7-day usage side by side; the accounts guide covers it, and I wrote it up separately in a post on sharing accounts between machines.
Question 2 — what did this session cost?
Every session's card, its row in the session list and its detail panel show its spend, including its subagents', priced from ccdeck's own rate table.
In the Usage panel, By session lists a row per session active in the period. A session that has left the canvas shows the end of its id, like 8c3f0e17.
Two markers are worth knowing, because they are the deck refusing to guess:
- not priced stands where a dollar figure would be when there is no published rate for the model. Its tokens are counted; its dollars are not. New rates arrive with new releases.
-
A figure ending in
+, such as $11.19+, is a minimum: some of its tokens are on a model with no rate. Hover it — a card names the model, and the Usage panel and the Projects report say how many tokens have no rate.
Question 3 — where did the month go?
Under the quotas, pick today, month or all. Month starts on the 1st, not 30 days ago; all is every transcript on disk.
These totals come from ccusage, a separate tool that reads the transcripts both CLIs leave on disk. The deck installs its own copy with npm the first time it needs one, or uses a ccusage already on your PATH. Because ccusage reads the transcripts, the totals cover every session on the machine, even ones no longer on the canvas.
Usage history (press H) opens on 30 days, with 7, 14 and 90 a click away. Click a day's bar for its tokens and its cost by CLI and by model.
Demo data. The last bar is today, clicked.
By project, per account
For Claude Code, the accounts panel (A) has a Projects report on each account's ⋯ menu: what that account spent in each project, by day.
Demo data. The footer says the dollars have been matched to ccusage's.
Work is counted for the account that was active when each message was sent. Work no account can be tied to is listed apart as Unattributed usage and left out of the totals.
Read the dollars correctly
This is the most important section of the post:
- These are API prices. Every dollar is the tokens priced at the providers' published per-token API rates. The deck does not know what your plan bills you. On a subscription, think of it as "what this would have cost on the API".
- ccdeck's table is the base rate: no Batch discount, no data-residency multiplier. Claude Code's fast mode is priced at its own rates. Codex session cards use the standard rate without a long-context surcharge; the Session usage view can also compare Standard, Fast and Flex estimates.
- ccusage measures a session and a day separately, so the By session rows can add up to more than the total above them.
- ccusage dates sessions in UTC, while the totals use your local day. Early in your morning, By session can say No session is dated today yet.
What it does not do
- It does not read your bill. No invoice, no plan price, nothing from a billing API — only the transcripts on this machine.
- Only this machine. Sessions you ran elsewhere are in that machine's deck, not this one.
- The Projects report is Claude Code only; Codex work is never in it.
- Quota needs a subscription login. API-key, Bedrock and Vertex users get spend but no quota bars.
-
Totals need ccusage. If it cannot be read, Usage can fall back to spend on this board, counting only sessions on the canvas; Usage history says why. Installing npm, or putting
ccusageon the deck's PATH, fixes it.
Try it
npx ccdeck
Run a session, then press U.
- Guide: https://ccdeck.dev/guides/cost-and-quota/
- Repo: https://github.com/BarganConstantin/ccdeck
- Licence: AGPL-3.0
Top comments (0)