Usage and costs¶
Use this page to read spend and quota from the command line and to set limits. For the charts, see the Usage tab.
- To see where you stand:
tclaude usageandtclaude costs. - To cap spending: see Usage limits and budgets, or Open usage limits & budgets… in Config › Usage & costs.
Operators and agents can query account quotas and recorded costs through the agentd daemon. The commands do not access the private database or provider credentials, and do not trigger provider API requests.
tclaude usage
tclaude usage --json
tclaude costs
tclaude costs --from 2026-10-01 --to 2026-10-03 --json
tclaude costs --self --json
tclaude costs --json --days --agents
tclaude costs --models --harnesses
Agents need usage.read and costs.read, respectively. Both are installed by
tclaude setup --install-default-agent-permissions (or --install-all).
Existing installations need to rerun that setup option to add them. Explicit
per-agent denies still take precedence. Human operators have implicit access.
--self requires an identified agent and includes costs attributed to its
stable agent ID across linked conversation generations.
Usage¶
tclaude usage replaces the former Anthropic-only direct API command. Its
--json format is now the daemon's multi-provider response, not raw Anthropic
JSON. GET /v1/usage/summary serves the same response over the agent socket.
The response contains generated_at, account scope, windows, and
coverage_warnings. Each observed provider/window includes:
pct: last observed percentage consumed, with nativeused_unitsandlimit_unitswhen known.observed_at,age_seconds, andsource: the reading's freshness and origin. Observation time and age are omitted when a legacy Claude cache is the only source: its overall refresh timestamp cannot establish each bucket's age.resets_at: reset time, when reported.status:current,stale,reset, orunknown_age;availableis true only for a current reading. A reset reading retains its old percentage as historical information; it does not assert current usage is zero.forecasts: the Usage tab'sspan,recent, andfitpredictions, including status, percentage points per hour, predicted limit time, and forecast sample window. The span estimator uses a seven-day history view.
Missing windows are omitted; an empty array means no quota observations are
available. Do not interpret an absent quota as unlimited capacity. Forecast
freshness is independent of the current reading: Codex cache readings can be newer than
sampled history. Check the forecast's status before using its rate or ETA.
Forecasts need at least three samples over thirty minutes and pause when stale.
These quotas and forecasts describe shared account usage, not just the caller.
Coverage warnings identify OpenCode activity lacking recent native readings.
Gemini session logs expose tokens and context usage, but no account-wide quota
windows are captured by tclaude. Gemini spawns therefore have no quota gate;
check the CLI’s /model quota display. Gemini costs are grouped under
google, using recorded model token counts and list pricing; they count as real
API spend or what-if per cost.gemini_billing (see docs/harnesses.md).
Costs¶
GET /v1/costs serves the cost response. from and to are inclusive dates in
the daemon's local timezone, defaulting to month start and today. Requests must
have ordered dates and span at most 366 days. self=true selects the caller's
stable agent ID.
JSON defaults to a compact summary: the range, generated_at, timezone,
scope, total_usd, real_total_usd, what_if_total_usd, cost_kind, and
providers rollups. Each rollup has name, total_usd, real_total_usd,
what_if_total_usd, and cost_kind when there is spend. Native Copilot credits
appear as virtual_cost_credits when recorded.
today_real_usd and today_what_if_usd count today only when it is in the
requested range. agent_id is present for self queries.
Details are opt-in and can be combined, in both text and JSON output:
--days: daily totals, including zero-spend dates in the requested range.--agents: detailed per-day conversation costs, with provider, model, and stable agent attribution when known. This can be a large response.--models: totals grouped by the last observed model for each agent/day.--harnesses: totals grouped by coding harness.
The daemon accepts matching boolean query parameters (days=true,
agents=true, models=true, harnesses=true). Unrequested categories are
omitted entirely; requested empty breakdowns are empty arrays. All summaries
and breakdowns use the same costs as the dashboard, and all respect --self
and the requested date range. Unknown provider, model, or harness attribution
is grouped under unknown.
Recorded API costs and hypothetical subscription equivalents remain separate.
total_usd can contain both: use real_total_usd when comparing recorded API
spend to a monetary budget. what_if_enabled follows the operator's
cost.show_on_subscription setting. WHAT-IF values are omitted from spend
when disabled. Dashboard display multipliers never change these raw amounts.
A conversation created from copied history (a clone, a cross-node teleport or
move, a bundle or .paf import) records only its own spend; the copied
history's spend stays with its source. Claude Code transcripts drop their
restored cost meter when copied, and Codex, Gemini and OpenCode cost readers
skip usage recorded before the copy landed.
Agents ignored from the dashboard's Costs view (the ⊘ row button) are left out of every summary and breakdown here, as they are from the dashboard totals and usage limits. Restore them from the Costs view's Ignored list.
An agent whose model calls went through a peer's model gateway (usage
sharing, or a requester-paid worker) is ignored on its own, with the reason
"billed to
Cost data covers recorded tclaude sessions, not the provider's entire invoice.
Model attribution follows the dashboard's Costs view: each conversation/day slice uses the
last observed model. generated_at is the response time, not proof that all
sessions have recently reported costs. These queries do not enforce budgets; usage limits and budgets
are described below.
Usage limits and budgets¶
tclaude can watch spend and quota usage against budgets you set, and act as they fill up. There are two kinds of rule, which work differently:
- Limits measure a total with one shared counter: the whole instance (a global limit, e.g. "$500 a month"), one group's members (a group limit), or a provider's account quota window (global only, e.g. Anthropic's 5-hour window).
- Usage profiles are named sets of per-agent rules. Each agent a profile applies to gets its own counter, e.g. "any agent: tell it at $5, ask it to wrap up at $15, stop it at $18".
Every rule is a metric, a period, a budget and a ladder of steps:
| Part | Values |
|---|---|
| Metric | total_usd (the Costs view's figure: recorded API spend, else the subscription-equivalent estimate), real_usd, whatif_usd, window_pct (global limits only) |
| Period | day, week, month (daemon-local calendar), lifetime (usage profiles only: the agent's whole life, across reincarnations) |
| Step | a threshold in percent of the budget plus an action |
Step actions:
notifymessages the agent (its inbox) and/or the operator (Messages, plus a desktop notification when enabled). It can repeat every N percent or every N minutes while the value stays above the threshold.wrap-upasks the agent to stop starting new work, write a handoff summary, send it to whoever assigned the work, and stay idle.hard-stopkills the agent's process.block-spawn(limits only) refuses every new spawn the limit covers, including the operator's, until the period rolls over or the limit is raised, disabled or removed.
On a limit, agent-directed steps reach every running agent in its scope. Every step other than a plain agent notify also tells the operator, so nothing drastic happens silently. A rule in dry run only tells the operator what each step would have done.
Which usage profiles apply to an agent¶
Profiles are assigned at layers: the global default, a group, and an
agent. The nearest non-empty layer wins as a whole: the agent's own
profiles, else the profiles of every group it belongs to (all of them apply,
each with its own counter), else the global default. A spawn profile can
carry usage profiles too. Spawning through it copies them onto the new agent,
where they apply on top of its group or global profiles; they never replace
them, so neither a default spawn profile nor an agent picking a spawn profile
sheds a budget. To replace the inherited layers, a human picks a spawned
agent's profiles explicitly (tclaude agent spawn --usage-profile …) or
assigns profiles to the agent. A clone keeps its source's own profiles, and a
limit that blocks spawns blocks clones too.
Readings, timing and edge cases¶
- Rules are evaluated every three minutes on the daemon's usage timer, even with the dashboard closed. Costs can be reported late, so leave some room between a wrap-up and a hard stop.
- A step fires once per period and budget. Raising a budget re-arms its ladder at the new amount; a new period starts it over.
- A stopped agent's steps wait until it runs again, so a hard stop crossed while it was offline still applies on resume.
- A hard stop stays in force for the rest of its period: an agent in scope that runs again while the value is still past the step is stopped again on the next evaluation, and the operator is told. Extend the budget, or snooze or exempt the agent, to let it run.
- A group limit counts the current members' spend, so an agent leaving the group takes its spend for the period with it.
- Quota-window limits act only on a current reading.
- Ignored and peer-billed conversations do not count, as in the Costs view.
Managing rules¶
In the dashboard, usage profiles sit beside the spawn and sandbox profiles:
- 💰 chips: in the Groups toolbar for the global default, and on each group row for that group's profiles, next to the 🧠 and 🛡 chips. Pick one profile inline; several open the manager.
- Spawn dialog: a Usage profile field, inherited by default.
- Spawn profile editor: the usage profiles that profile adds to its agents.
- Group template editor: the usage profiles a group deployed from the template starts with, as its group layer.
Each of these offers + new usage profile…, which opens the manager on top, so the pick is there before the first profile exists. - Agent rows: a 💰 badge once an agent has used half a budget or a step has fired, and a "💰 usage budget…" entry in the row menu. - Dock: a Usage profiles section with ★ for the global default, and a Usage limits & alerts section listing the active global, group and fleet limits with their readings. A card's ⚙ edits, clones or deletes the limit and its alert ladder; + adds a limit.
Usage limits & budgets (the Usage tab's Limits section, Config › Usage & costs, the command palette, the limit banner, or any of the above) has four tabs:
- Limits: global and group limits with their live readings, an enable toggle, and presets (monthly or daily spend cap, quota window guard).
- Usage profiles: create, clone and edit profiles and their rules.
- Assignments: the global default, each group, each spawn profile, each group template and individual agents.
- Agents: each agent's budgets, with snooze, exempt and per-rule extra budget.
The Usage tab's overview also lists every enabled limit's reading.
The same operations are available on the command line:
tclaude usage rules # limits, profiles, assignments, readings
tclaude usage limit add --name monthly --period month --budget 500 \
--step 50:notify:operator --step 90:wrap-up --step 100:block-spawn
tclaude usage limit add --scope group --group backend --name weekly \
--period week --budget 100 --step 80:notify:agent+operator:every=5%
tclaude usage limit add --name 5h --metric window_pct --window anthropic:five_hour \
--step 90:notify:operator --step 98:wrap-up
tclaude usage profile set default --name budget --period lifetime --budget 20 \
--step 50:notify:agent --step 80:notify:agent+operator \
--step 100:wrap-up --step 120:hard-stop
tclaude usage assign --scope global --profile default
tclaude usage assign --scope group --target backend --profile strict
tclaude usage assign --scope spawn_profile --target reviewer --profile cheap
tclaude usage assign --scope template --target feature-team --profile strict
tclaude usage adjust worker-1 --rule profile:1:budget --extra 10
tclaude usage adjust worker-1 --snooze 60
tclaude usage self # an agent's own budgets
A step is AT:ACTION[:TARGETS][:every=N%|every=Nm]. --file reads a rule
(or, for profile set, an array of rules) as JSON instead. adjust changes
one agent: --extra adds budget to one of its rules, --snooze holds its
steps for a while, and --exempt takes it out of usage profiles (shared
limits still count it).
Reading rules needs usage.read; an agent reading them sees the limits,
profiles and shared assignments but not other agents' budgets or
adjustments (usage self shows its own). Changing them needs
usage-rules.manage.
That permission is not default-granted and group ownership does not confer it,
because an agent holding it could lift its own budget.
Fleet limits: spend across peers¶
With federation, budgets can span machines. Three peer grants, all off by default, decide what a peer gets from this node:
| Peer grant | Gives the peer |
|---|---|
usage.read |
this node's spend totals (today, this week, this month), its limit readings and a count of agents near or over budget, so the peer's fleet limits can count this node |
usage-rules.manage |
this node's usage rules from the peer's dashboard, as if local: limits, usage profiles, assignments, and extend, snooze or exempt |
usage-rules.enforce |
the peer's fleet limits may act on this node's agents in the granted groups (an unscoped grant also covers agents in no group): notify, wrap up, hard stop, block spawns |
A fleet limit is a limit over spend summed across nodes. Its target is
all (every trusted peer), pool:<node pool> (a local node
pool as a sub-fleet) or peer:<peer>, and by
default it counts this node too. Only members sharing usage.read count,
and each reading says how many did. A member's total counts while it is
under ten minutes old, so an unreachable member keeps its last reading for a
while rather than dropping to zero. Fleet limits take the day, week and
month periods and the dollar metrics. Each member sums its own calendar
period, so members in other time zones roll over at their own midnight.
The limit's node runs the ladder once a minute. Operator steps tell its own
operator. Agent-directed steps reach this node's agents (when it counts
itself) and, on each member that granted usage-rules.enforce, the agents
the grant covers. The member performs each step itself, records it once and
tells its own operator what the peer's limit did. Members learn the fleet's
percentage only, never its spend or budget, so no member can work out the
others' spend. Steps that fire while a member's grant is not yet known (it is
offline, or the limit's node just started) wait for it and are delivered
once it answers. A spawn block or a fired
hard stop is a lease of three minutes that the limit's node renews while the
total stays past the step: a member keeps refusing spawns, and stops a
covered agent that runs again, until the lease is released (the limit is
lifted, disabled or removed, or its budget raised) or lapses because the
limit's node went quiet. Revoking the grant ends it at once.
# On each member: share usage with lead-node and let its fleet limits act on builders
tclaude federation grant lead-node usage.read
tclaude federation grant lead-node usage-rules.enforce --scope group=builders
# On lead-node: a fleet-wide monthly cap, and a sub-fleet cap on a node pool
tclaude usage fleet limit add --target all --name fleet --budget 5000 \
--step 80:notify:operator --step 100:block-spawn
tclaude usage fleet limit add --target pool:gpu-rigs --name rigs --period week \
--budget 800 --step 90:notify:agent+operator --step 100:wrap-up --step 120:hard-stop
tclaude usage fleet # limits, readings per node, what each peer shares
tclaude usage fleet limit set 2 --budget 1000 --name rigs --period week --step 100:wrap-up
tclaude usage fleet limit rm 1
tclaude usage fleet lists every trusted peer with the usage grants it
holds for this node, its totals and its limits, and the peers' fleet limits
currently blocking or stopping anything here. Fleet limits and that view
stay with this node: no peer reads another peer's usage through it.
In the dashboard, the usage dialog's Fleet tab holds the same: fleet
limits with presets and an editor, each limit's reading per member (counted,
shares no usage, stale) and whether its steps act on that member's agents, a
nodes table with each peer's totals, limits and the grants it shares, and the
peers' fleet limits in force here. The palette opens it as Fleet usage
limits…, and ⚙ Fleet config › Usage sharing links to it. Where a peer granted
usage-rules.manage, its row has manage its rules…, which opens the full
usage dialog against that peer; the same is reachable from the peer's popup in
the fleet strip and from the 💰 usage rules button on its peer view. The
spend banner also shows fleet limits past a step and peers' blocks or stops
in force here.
The fleet views carry a 💰 fleet control: in the fused Groups toolbar and
in the map's toolbar. It shows the tightest fleet limit's percentage in green,
amber or red, a ⛔ count while peers' fleet limits block or stop anything
here, and every reading on hover; a click opens the Fleet tab. While the
fused toolbar acts on a peer that granted usage-rules.manage, it also offers
💰 usage rules on
The former Spend limits settings (cost.daily_limit_usd,
cost.monthly_limit_usd) are converted on the next usage tick into global
limits on recorded API spend with operator alerts at 80% and 100%, and are
removed from config.json.