Usage

How close am I to a rate limit? You buy your own tokens, so managing your own limits is part of the deal. Usage is the answer to that question for Claude Code, Codex, GitHub Copilot and Cursor. Cursor's gauge is read from its dashboard rather than a supported public personal-usage API, and it remains separate from the token-based cost estimate attached to a completed Cursor job.

The point is to see the headroom before you dispatch a batch of twenty jobs, rather than discovering it three jobs in.

Two places it shows up#

The status strip at the top of board carries a chip per meter, as many as the header has room for, with the rest behind an … flyout. You choose which meters earn a chip per harness, so the strip stays the one number you actually watch. Choose a named meter, all (the default, one chip per meter), or hide. Cursor's choices include cursor-models and other-models.

The Usage screen is the full breakdown the strip omits: one card per enabled harness, each meter with its percentage, its pace, a reset countdown, when the reading was taken, and the error from the last attempt if it failed.

Pace is the one worth explaining. A meter colours by projected end-of-window usage rather than by where it is right now, so 40% used with four hours left in the window reads differently from 40% used with twenty minutes left. Sitting at half your quota is only alarming if you are going to blow through it.

What each harness can actually report#

Same honesty rule as everywhere else: a reading nobody has observed is reported absent rather than invented.

• Claude Code reports its 5-hour and weekly windows, read from the same credentials Claude Code itself uses: the macOS keychain on a Mac, and ~/.claude/.credentials.json on Linux and inside WSL2. Subscription sign-ins show their windows there too. If you use an API key instead, the same windows arrive from the rate-limit headers.
• Codex reports the windows on your ChatGPT plan, including the per-model sub-quotas. Which window is 5-hourly and which is weekly varies by plan, so the labels come from the windows themselves.
• GitHub Copilot reads the billing entity's AI-credit report and budgets. GitHub exposes activity and configured budgets, but not a same-scope included capacity or budget consumption denominator. The snapshot can therefore be healthy and meterless, especially while current-period billing is still empty. toryo reports that limitation instead of fabricating a utilization percentage.
• Cursor reports the included allowance, plus cursor-models and other-models, the two bucket bars in Cursor's own Plan & Usage pane. Each bucket appears only when reported, never as an invented zero. When the account configures a spend cap, it also reports an on-demand meter and headroom. It reads the undocumented, unversioned dashboard Connect RPC using the signed-in Cursor desktop session on macOS. This is not an official personal-usage API: absent or expired credentials and endpoint or payload changes make the reading unavailable or unknown rather than zero.

These are observed provider gauges. They are separate from the API-equivalent cost estimate attached to a completed job.

Admission and cost are different questions#

Dispatch applies the admission policy you select to observed usage. Included policy considers the included meters. Paid policy can continue against a provider-reported paid allowance only when the provider exposes enough bounded information to enforce it. Unavailable, disabled, meterless, or malformed gauges produce an explicit unknown state and follow the documented fail-open policy; they never become an invented zero.

For newly completed Codex and Copilot jobs on a model in toryo's pricing table, totalCostUsd is an API-equivalent estimate computed from token usage. It does not claim that your subscription was charged that amount, and it is not a Copilot AI-credit reading. Cursor jobs are priced the same way but against Cursor's own published per-token rates, which is what Cursor actually bills usage-based against a request pool, so that figure is nearer a real charge while still modelling neither the allowance a seat starts with nor team surcharges. Claude jobs carry Claude Code's own cost report when it gives one, and otherwise an estimate from the same pricing table. Claude estimates price Opus 5, Opus 5.5 (Claude Code's default) and Sonnet 5 at their own rates, and bill one-hour prompt-cache writes at their higher rate. An unknown model omits totalCostUsd instead of returning zero, and historical jobs are not backfilled when a price is added later.

Why it does not update constantly#

The endpoints these numbers come from rate-limit themselves. Claude's starts refusing at roughly once a minute across every client sharing your token, which includes Claude Code itself.

So readings are cached and re-polled on a cadence rather than live. A failed poll keeps showing you the last good numbers, with the time they were taken, instead of blanking the gauge and hammering the endpoint. Board also stops polling while its window is hidden.

Poll now on the Usage screen forces a fresh read of every enabled harness, ignoring the cadence, for when you want the number this second.

What you can tune#

On the Settings screen, or from a terminal:

• Shared poll interval, five minutes by default, with a one-minute minimum.
• Per-harness interval. Slow it down freely; speed it up only as far as its endpoint's polling floor allows.
• Which meters ride in the status strip, per harness: a named meter, all, or hide.
• Warning threshold, projected end-of-window utilization, defaulting to 80%. The danger colour means usage is projected to hit 100% before reset.

Whether a harness appears at all follows this machine's harness switch, not a Usage setting. See Harnesses.

toryo usage get         # the current readings
toryo usage poll        # force a fresh read
toryo usage providers   # what is registered, and which harnesses are switched on
toryo usage settings describe
toryo usage settings set --cursor-header cursor-models

Where things go wrong#

• Copilot is healthy but has no percentage gauge. The report exposed activity without a compatible capacity denominator. That is an honest meterless snapshot, not zero usage.
• Cursor usage is unavailable. Sign in to the Cursor desktop app on this Mac. If it is already signed in, the undocumented endpoint or its response may have changed; toryo reports that uncertainty rather than zero usage.
• A reading is stale. The last poll failed and you are looking at the last good numbers, which is deliberate. The card says when they were taken.
• A harness has no card. Usage shows every harness switched on for this machine. A missing card means the harness is off; see Harnesses. hide removes only its status-strip chips.
• Claude shows no credentials on Linux. Sign in with claude in that same environment (WSL2 counts as Linux), or set ANTHROPIC_API_KEY.
• Cost on a job is blank rather than zero. The job predates estimation, its model is not in the pricing table, or the harness supplied no usable usage. Existing rows are deliberately not rewritten by later pricing changes.

Full command surface: CLI & contract reference.