Usage

Review token usage and cost across every enrolled machine.

The Usage page at /ai/usage answers “what have my AI tools actually cost?” across every machine you manage. Each visit shows durable usage history immediately, fans a fresh collection job out to your online agents, runs ccusage --json on each of them, and aggregates the reports into one view broken down by day, model, and agent.

This page reports what the AI tools themselves recorded on disk, covering all local usage including work you did outside this control plane. The per-run figures on a Plan or Session come from the run’s own token counts instead — the two answer different questions.

How collection works

1. The request fans out

   Opening the page starts a collection against every enrolled agent. Agents that are offline, or whose control-agent build does not advertise the ccusage capability, are excluded from the eligible set and named in the status banner.

2. Each agent runs ccusage

   A job runs ccusage --json locally, with a 120-second timeout and a 16 MB cap on output. Results stream back as each agent finishes.

3. Reports are merged

   Daily entries from every agent are merged by date, then by model, then by agent. Successful reports are stored as they arrive, including partial collections. The whole collection has a 150-second deadline.

4. The page updates live

   Progress arrives over a subscription and is reconciled every two seconds until the collection completes. Stored totals remain visible while the current agents load. Refresh usage starts a fresh collection without blanking the history already on screen.

The status banner above the results always shows n of N compatible agents reported, and lists offline agents, agents needing a control-agent update, and any that failed with their error text.

Reading the results

Element	What it shows
Daily cost by model	Stacked USD per day across the selected range. Selecting a model in the legend charts it alone; selecting it again restores every model
Summary tiles	Total cost, total tokens, input, output, cache creation, and cache read for the current filters
Spend records	The highest rolling 7-day and 30-day spend across all retained dates, with each winning inclusive date span
Usage table	One row per day, expandable to models, expandable again to the agents that used each model
Grand total	The table footer, covering the selected range

Each agent row inside the table also names the sources ccusage attributed that usage to, so you can see which tool on that machine spent the tokens.

A day can carry an Unattributed tokens row. That is usage ccusage recorded without a model attached — it counts toward totals but cannot be charted against a specific model.

Date windows and filters

• Range — 30 days is selected by default. You can also choose 7 days or All data.
• End date — appears for the 7-day and 30-day ranges and defaults to today. The selected day is included, so a 7-day range contains that day and the six preceding calendar days. You cannot select a future day. All data hides and ignores the end date, while switching between ranges preserves it.
• Agent — derives its choices from the displayed aggregate, so an offline agent with stored usage remains selectable. The web control appears once more than one agent is available; iOS shows its picker whenever the aggregate contains an agent. Both also show it whenever a global agent is active. It narrows every chart, tile, and usage row without recollecting.
• Model — set by selecting a model in the chart legend. The summary tiles say so explicitly when they cover one model rather than the whole range.

Changing the range, end date, History/Live state, agent, or model refreshes the current view without starting another collection. Selecting a model and then narrowing the range past the point where that model appears drops the model filter rather than showing a row of zeros.

Use the active agent

The Active Agent selector overrides this page’s saved Agent choice on web and iOS. The page selector becomes disabled and shows Controlled by Active Agent. Charts, summary tiles, table rows, and spend records follow the selected agent without starting another collection. An agent without usage in the selected range shows an empty result rather than totals for other agents.

Select None globally to restore your previous Usage agent filter. This underlying choice survives navigation and restarts, independently of the active agent and other pages’ agent filters. Collection progress still reports the collection across agents, and Clear history still clears history for every agent.

Spend records

The two spend records use fixed inclusive calendar windows across all retained dates. Days without usage contribute zero. If multiple windows have the same total, AIDE shows the one with the latest end date.

Spend records ignore the selected range and end date. They do follow History on / Live only, the agent filter, and the web model filter. When those filters have no matching usage, both records show an empty state.

History controls

Usage history is enabled each time you open the page. AIDE stores the last cumulative report from each agent plus the usage archived from earlier local histories. If an agent’s counters decrease, disappear, or later reappear because local tool history was cleared, AIDE treats the new counters as a new epoch and adds them to the preserved total.

• History on / Live only changes only what the page displays. Collection and durable recording continue in either mode, and the choice resets to History on on the next visit.
• Clear history asks for confirmation, then removes stored history for every agent and date. The current live collection remains visible. Reports completed before the clear cannot silently restore the deleted history; the next new collection establishes a fresh baseline.

The five-minute sidebar usage collection also updates this history. Its temporary collection jobs can be cleaned up without removing the durable totals.

Empty states

The page distinguishes several kinds of “nothing here”, so the fix is never a guess:

Message	What to do
No agents enrolled	Enroll a machine from the Agents page
No agents online	Connect an enrolled agent and refresh; stored history remains available when it exists
No compatible agents online	Update control-agent on an online machine to pick up the ccusage capability; stored history remains available when it exists
Usage collection failed	No agent returned a valid report — check the per-agent errors in the banner
No usage found	Agents reported successfully but ccusage has no daily usage recorded
No usage in this range	Widen the range to reach older usage

Notes

• Every load still runs a fresh collection, but successful cumulative reports are stored so clearing usage from an agent does not erase previously observed totals. Use Live only when you need to compare against what agents currently report from disk.
• The public GraphQL API keeps range: ALL as its default for backward compatibility. For LAST_7_DAYS and LAST_30_DAYS, pass endDate as a strict YYYY-MM-DD value to choose the inclusive last day.
• ccusage must be installed on the agent. A machine that cannot run it reports a failure rather than silently contributing zero.
• The agent does not rely on PATH alone. A service started by brew services inherits a bare PATH that hides Homebrew, npm, and bun installs, so the agent also searches ~/.local/bin, ~/.bun/bin, ~/.npm-global/bin, the directory holding its own node binary, and /opt/homebrew/bin and /usr/local/bin on macOS. Set CONTROL_AGENT_CCUSAGE_EXECUTABLE to a full path to pin an install the search misses.

Related pages

Costs

The model price catalog used to estimate run costs.

Agents

The agents each collection fans out to.

Sessions

Per-run token counts and cost.

Job details

The durable job each collection runs as.