v0.4.0

Weighted tokens replace tokens in+out

Every token figure on the page is now in weighted tokens: each kind of token a tool records, weighed by what the provider's API charges for it against an input token.

Until v0.3.4 the page counted input plus output and left cache out. That hid most of Claude Code's work. Claude Code sends almost everything new in a session as a cache write, and re-sends the conversation as cache reads, so its input is close to nothing and its in+out is mostly output. Codex counts the same new context as input. Next to Codex, a Claude-heavy project, device, or teammate looked several times smaller than it was, and PROJECTS ranked the busiest Claude work below lighter work.

Tool	Input	Output	Cache write	Cache read
Claude	1	5	1.25, or 2 for a write kept an hour	0.1
Codex	1	8	1	0.1
Grok	1	5	1	0.25
Hermes	as the tool its login bills to; Claude's for an unknown route

Weighted tokens follow what quota spends better than in+out did, but they are not any provider's quota formula. The first-run guide and the ? help say what one weighs.

The JSON keeps usage, days, share, and window_tokens as input plus output, with the meaning they had, and adds burn, burn_days, burn_share, and window_burn beside them, along with fresh (input, cache writes, and output: the new context, whatever the tool). The schema version stays 4. See docs/json-schema.md.

This device

• PROJECTS and USAGE count weighted tokens over your local days: today since local midnight, and 7, 30, and 90 days as the last 168, 720, and 2160 hours. SESS counts the sessions active in the period, not those started in it.
• Projects group better. A folder outside any repository counts with the project folder above it, worktrees that were deleted stay with their repository, and Codex chats make one project. Two long paths that would print alike show what tells them apart.
• Coverage. Where the ledger holds less than 85 days of a tool, the PROJECTS title says since when, as · claude since Sep 2, and those projects' 90D is dim. Claude Code deletes transcripts after 30 days by default; the guide says how to keep 90.
• Claude Code sessions are dated by their last message, cache writes kept for an hour weigh as such, and output Claude Code tracked beyond its transcript counts in the hour it was tracked. Replies whose transcript ends without a final count are counted in transcript_gaps.
• Codex sub-agents count with their family, the history a forked session replays is no longer counted again, and a session whose log several account folders hold goes to the account Codex's own thread database names, else to the one whose weekly window resets when the session's own rate-limit reading says, else stays where it was. A session whose log now holds fewer tokens than were counted is taken back to what the log shows.
• Hermes history is spread over the hours a session worked, so a bot's first run no longer puts months of tokens in one hour, and auxiliary calls on an unknown or auto route bill to the session's own login. A chain of sessions whose first one is over 90 days old is counted once.
• Claude Code's quota is read with the newest Claude Code installed, from PATH, the native installer, Homebrew, npm, the desktop app, or an editor extension, so an old copy first on the scheduler's PATH no longer leaves you without a reading.
• The menu bar app shows weighted tokens, the new ATTENTION lines, estimated totals, and reinstalled devices. Next to an ai-usage before v0.4.0 it shows what that one reports, labeled tokens in+out.

Team

• DEVICES × SUBSCRIPTIONS and the devices' status table count weighted tokens over UTC days, as devices send them, and say so: 7d UTC. This device's own row can differ from PROJECTS for that reason.
• Columns that do not fit fold into a REST column, so each row's cells add up to its TOTAL at any width.
• A total estimated from a device on an earlier release is marked ~, and the legend says which devices and what to do.
• The SUBSCRIPTIONS column of how many devices use a subscription is headed DEVICES, and a subscription with no reading says why in place of its bar, such as which device needs a newer Claude Code.
• A teammate's last error says when it happened, in ATTENTION, the devices' NOTE, and the menu bar app.
• A gap in a teammate's reports counts only time this device's own team reads saw, so a laptop that slept no longer shows gaps for every server.
• ai-usage team forget-device takes the start of an id, at least the 8 characters ATTENTION prints.

Forecasts and ATTENTION

• A window is forecast at the faster of its average pace since it began and its recent pace, the slope of the last day's readings, from this device's samples and the team's reads. A line forecast at the recent pace says so. A week that speeds up is caught days earlier.
• New ATTENTION lines:
  • TIGHT: a window of an account on this device will end its reset 85% to 99% full.
  • OUTSIDE: a window rose 5 points or more in the last day while no device of the team spent on it, so someone outside the team uses the subscription.
  • NO READING: a subscription used in the last 7 days has no quota reading, with the reason and what to do.
  • DUPLICATE: a reinstalled device's old record is still on the relay, with the forget-device command that removes it.
• OLD names what an old release cannot do, such as read the Claude quota, and says to reinstall it.
• +N more says how many of each kind it hides.
• The header dates the relay by the older of the last push and the last team read, and warns once the team was last read over an hour ago.

Reliability

• state.json is copied to state.json.last after every save. A state.json that does not parse is kept as state.json.bad, and the run goes on from the last copy instead of from nothing.
• A run without the network is called offline, as one problem, and the tools it read stay ok.
• A clean run clears the last error. A Claude Code that cannot read the quota is no longer an error that marks the device failed: it is a missing reading that names the install to update, such as update Claude Code to 2.1.208 or newer.
• Errors from a tool's command end with what it last printed, up to 100 characters.
• Codex's quota read has a budget of its own and one retry, so a slow answer no longer costs the reading.
• A Claude folder is asked for its quota when the desktop app used the same account more recently than the folder's own sessions.

Performance

• Claude Code transcripts are parsed once: later runs reuse what was parsed, read only the lines added since, and skip prompts and tool results without decoding them. On a long Claude history, a run no longer spends most of its time parsing.
• Scheduled runs start at a point of their own in the minute after the quarter hour, so a team's devices no longer reach the relay all at once.

Compatibility and upgrade

Mixed-version teams. v0.4.0 adds three fields to the snapshot: weighted days, weighted totals per quota window, and when the last error happened. A release before v0.4.0 rejects a snapshot with fields it does not know, so a device sends them only once its last team read, at most 3 hours old, shows every teammate on v0.4.0 or later. Until then every device sends the snapshot older releases read, no device loses sight of the team, and the team's weighted tokens are estimated from input and output and marked ~.

• Releases from v0.2.5 on update themselves within 15 minutes. Older ones need install.sh again; the legend and ATTENTION name them.
• A device that is retired, or silent for over a week, still holds the fields back until ai-usage team forget-device ID forgets it. A device that expired from the relay is remembered for 90 days, so a laptop on an old release that wakes up later never meets a snapshot it cannot read.
• A build from source now reports devel. One built from source before v0.4.0 reports dev and holds the fields back until it is built again. A hand build with a suffix counts as the release before the suffix, so build with one from v0.4.0 on, such as v9.9.9-local, not the v0.0.0-local earlier docs suggested.
• One case is left: a device the team has never seen, freshly installed with a release before v0.4.0 that someone pinned, can read the new snapshots on its first run and skip them until it updates itself at its next run, or until the others close the gate at their next team read, within about 20 minutes. The installers always install the newest release.

Relay. If you run your own relay, deploy it from this release before your devices update: it accepts the new fields and the older snapshot both. A relay that answers the new fields with 422, such as an older self-hosted one, gets the older snapshot in the same run and is not offered them again for 24 hours. The team read now says when the relay first stored each device, so a forgotten device is told apart from one that expired. Scheduled runs read the team when the last read is 20 minutes old, every other run, instead of hourly: about 32,000 store commands a month per device, so Upstash's free plan fits about 15 devices. See docs/relay.md.

State. The first v0.4.0 run migrates the ledger to count every kind of token per hour, and keeps the file it started from as state.json.pre-v0.4. Each session's totals by kind of token are spread over the hours its logs show, where they are still there, and else over the hours the earlier release recorded. Sessions v0.4.0 reads differently, such as Codex sub-agents and Hermes auxiliary calls an earlier release counted apart, move with their counts, so the upgrade counts nothing twice. To go back to an earlier release, stop the scheduler, put state.json.pre-v0.4 back as state.json, and install that release. If an older ai-usage, such as a second install, collects after v0.4.0 did, the next v0.4.0 run merges what it counted, capped to what the logs show. A state.json a later release saved is left as it is: v0.4.0 still updates itself, and does not write over it.

90-day coverage. Weighted tokens reach back as far as the ledger does. Claude transcripts older than 30 days are usually gone, so Claude's 90D on an existing install is weighted from the totals the ledger kept, not re-read; PROJECTS says since when a tool is covered where that is under 85 days.

Known limitations

• Weighted tokens are a proxy for quota. How many weighted tokens a percent of quota is differs by plan and provider and is not calibrated.
• Claude Code transcripts that end without a final count are counted as they are, and shown in transcript_gaps, not estimated.
• Codex's thread database names the account that created only some threads, so a session several account folders share can still stay with the first folder.
• The page no longer prints tokens in+out. Scripts that need them read usage and days in the JSON; a report saved by an earlier release still shows them, titled tokens in+out.
• Going back to v0.3.x is supported only by restoring state.json.pre-v0.4.

Full Changelog: v0.3.4...v0.4.0