v0.5.1

The menu bar app: every alert, in the report's words

The popover's first line still says what matters most: what is out and when it is back, or what runs out and when. The rest of the report's ATTENTION was a count, "+3 more", and the app worded what it showed on its own. Now it shows everything the report says, in the report's words.

• Alerts. The first line ends with a link, "11 alerts ›", which shows every entry of ATTENTION in place of the tab, in the report's order: one line each, with the mark of its kind, what it is about, and what to know, as the console says it. A line the popover cuts is whole in its tooltip. A click on a line opens its subscription in Limits, or its devices in Usage, and Back goes back to the tab. The last line, Most room, names the subscription with the most left. See the alerts.
• Idle. A paid subscription the team has not used for a week is the last alert, a dim line, "idle 9d, paid and unused", as the report's new IDLE says below.
• The countdown. A Limits row that runs out before its reset counts down to when it does, "↘17h 19m" in orange, in place of the time until the reset, and names the window under the row: "7d runs out ~Fri 08:59 · resets Mon 02:40". When an old reading says it has run out by now, the row says "↘ ran out".
• Details. A click on a subscription now also gives the forecast of the window that runs out and the pace it takes, "164% at reset · this week's pace"; how old its reading is and which device took it; what fills it from outside the team; who spent the window since it began, in weighted tokens, "build-01 84M, scout 35M +8"; when it was last used; and why the report calls it idle or could not read it. See the details of a subscription that runs out.
• Not read. The line under a tool's subscriptions that names those with no reading, such as "Not read: unknown · not logged in on build-01 …", is cut at the popover's width. A click on it opens the report's reason for each whole, with what to do, and so does the alert of a subscription not read.
• Devices. Usage says a device's problem under its row in the words of the status view's NOTE: the error it reports, since when it has been silent, or the release it is behind and why it does not update.
• An old reading stays in sight. When the reading behind the first line is old, the line keeps its age, such as "reading 1d old", at every width, ahead of the count of the others.
• Terminal. The menu under the dot beside the first line has Open Report in Terminal, Device Status in Terminal, and All Projects in Terminal. Each opens a Terminal window that runs ai-usage report, with --devices or --projects, with the PATH and state folder the collector uses. Device Status is left out when this Mac is the team's only device.

The README's Menu bar app has both pictures, in dark and light.

IDLE, and where tokens with no login come from

ATTENTION has a new kind, IDLE, and NO READING now says where the tokens no login was known for come from:

 NO READING  claude unknown  not logged in on build-01 (~/triage/.claude): run claude and log in
 IDLE        grok 7f3b9c21   idle 9d, paid and unused

• IDLE is a paid subscription with a reading that no team device has used for 7 days, by when it was last used, and that nothing says someone outside the team uses: its weekly window is under 1%, or began before that last use. It is dim and comes last, since nothing about it is due soon: use it again, or cancel it. It takes the place of UNDER for that subscription, and is never said of unknown, Hermes, or a free plan.
• NO READING for unknown names the device, and the folder when it has several, whose tool answered that nobody is logged in, with how to log in, and the row of unknown in SUBSCRIPTIONS says what to do. Without such an answer, it says nothing rather than guess.
• JSON. Each attention entry has subject and text, its line as the console says it at its longest, and each team device has note, its NOTE in the status view, so an agent can show what the console says without wording it again. Clocks in them are in the time zone of the machine that made the report, and ai-usage report --from fills them in for a report saved without them. attention can hold the new kind idle, which a reader that does not know it should skip. The schema version stays 4. See docs/json-schema.md.

The snapshot does not change: a device on v0.5.1 works all of this out from what its teammates already send, whatever release they run.

macOS: an update no longer costs a scheduled run

On macOS 27, launchd pins the launch agent it loads at login to its binary's code signature. ai-usage is signed ad hoc, so the signature is the binary's hash, and every release has another. Once an update had replaced the binary, launchd refused the agent's next run, with OS_REASON_CODESIGNING, and at the run after it repaired the pin and ran the new binary. So each update cost a Mac one scheduled run, and its reading was half an hour old before the next one.

• A run you start that installs a release, such as ai-usage update, the menu bar app's Update button, ai-usage, or r in the view, now has launchd start the agent at once when launchd pinned it. launchd refuses that start and repairs the pin at a second one right after, so no scheduled run is refused, and it records the new binary for the next login too. The agent then collects, as at a scheduled run.
• A scheduled run that installs a release cannot do the same, since launchd does not start the agent while it runs, so launchd still refuses the next run. Any run you start after that refusal has launchd start the agent, which repairs the pin and collects: ai-usage, ai-usage status, ai-usage report, or the menu bar app, which reads the report every minute. With the app open, the refused run is made up within about a minute.
• ai-usage schedule status says when launchd refused the agent's last run. When launchd still refuses it after the repair, ai-usage status shows that as a schedule problem, with ai-usage schedule install as the fix.

The README's Troubleshooting says how to see a refusal in launchctl print.

Compatibility and upgrade

What to do. Nothing. Releases from v0.2.5 on install v0.5.1 within 15 minutes, and on a Mac the menu bar app updates with the binary. On macOS 27, a release before v0.5.1 makes that update, so launchd can refuse the run after it once, as before. The run after that brings the agent back, and so, as soon as launchd has refused it, does any ai-usage you start, or the menu bar app's next read of the report, since both run v0.5.1 by then.

Other systems. An agent launchd pinned to nothing, as on macOS 26 and earlier, is left as it is, and so are cron, schedule run, and Task Scheduler.

State. Nothing changes in the state folder or the snapshot. The JSON gains subject, text, note, and the idle kind, and no field changes its meaning.

Known limitations

• After a scheduled run installs a release, launchd still refuses the next scheduled run. A run you start after that, or the menu bar app's next read of the report, makes it up.
• ai-usage schedule install loads the agent from the command line, which launchd pins to nothing until the next login. launchd still records the binary it pinned before, so the first run after that login can be refused once, and launchd repairs it at the run after.
• A run you start while the agent runs leaves the pin to launchd, which does not start the agent twice.

What's Changed

• Report the app's words: ATTENTION subject and text, device notes, IDLE, and why tokens have no login by @neoromantic in #11
• Menu bar app: every alert, run-out countdowns, caveats, and the report in Terminal (#7) by @neoromantic in #12
• Keep the macOS schedule running after self-update by @neoromantic in #14

Full Changelog: v0.5.0...v0.5.1