Releases
Changelog
What’s new in each version of ai-usage, newest first. One-line installs from 0.2.5 on update themselves within about 15 minutes of a release; a Homebrew install updates when you run brew upgrade or ai-usage update. On a Mac, the menu bar app follows.
Releases
Install with Homebrew, on macOS and Linux.
- After a Homebrew install, run ai-usage once to start collecting every 15 minutes. The one-line installer works as before.
- A Homebrew copy never replaces itself. It tells you when a release is out, and its update command runs brew upgrade for you.
- One command adds the Mac menu bar app, on macOS 14 and later, whether you installed with Homebrew or the installer.
- A teammate’s machine on an older release now “should update”, and one that hasn’t after 7 hours is named, with the command to run on it.
A team’s today starts at your midnight, wherever everyone works.
- For a team across time zones, “today” in the team tables used to be the UTC day, which starts at 5 pm in Los Angeles. Now it counts from your own midnight.
- 7, 30 and 90 days still count UTC days, and say so.
- Claude Code’s reset times now read everywhere, even in slim containers with no time zone data.
- For scripts, the JSON says whether the team’s today is your local day.
Subscription details in the Mac app that say only what matters.
- A subscription’s details list who spent its window as the two busiest machines, then “+8 more”, and say since when.
- A forecast nobody has used since it would have run out now says where it “would reach” at the reset.
- How old a reading is, and which machine took it, now shows only when it matters: an old reading, or another machine’s.
- For scripts, the JSON adds when each window began and which machine took each reading.
Calmer, more honest forecasts, and easier-to-find buttons in the Mac app.
- Forecasts for weekly windows now measure the pace over at least a full day, so a busy first morning (or a provider resetting everyone’s week early) no longer cries wolf.
- “Recent pace” is now what you actually used over the last day, so a burst followed by a quiet afternoon reads as a normal day.
- If a forecast said a window would run out but nobody has used it since, it now says it “would run out” instead of claiming it did, and you get no notification for it.
- Mac app: a Team button next to the tabs, a proper menu button, a menu in clear sections, and a tidier About.
A Team window in the Mac app.
- See the whole team on one screen: every machine against every subscription, shaded by how much each uses.
- A Status view with each machine’s user, version, last report, tools, and what’s wrong.
- Sort by any column; switch periods (today, 7, 30, 90 days) and shares with the same keys as the terminal.
- The menu bar ring can now follow the whole team’s subscriptions, not just this Mac’s.
Every alert in the Mac app, plus “idle” subscriptions.
- The Mac app lists every alert the report has, in the same words, each one clickable.
- A running-out subscription counts down to the moment it runs out, with details on who spent it and when it was last used.
- New IDLE alert: a subscription you pay for that nobody on the team used for a week.
- Tokens nobody was logged in for now say which machine and folder to log in on.
- On macOS 27, an update you install by hand no longer costs a scheduled run, and one installed on schedule is made up by your next run.
History and notifications.
- New: how full each subscription got before every reset over the last 90 days, shared across the team. See which plan runs out every week and which sits mostly unused.
- Mac notifications when a window is out or will run out before its reset, at most once each when it will run out and when it’s out, per period.
- Fewer false “over” alarms right after an early weekly reset.
- Very large session log lines (huge pastes) are now counted instead of flagged as errors.
Token counts that reflect real work, and smarter alerts.
- Token counts now weigh each kind of token by what it costs, so Claude Code’s cache-heavy work is no longer hidden next to Codex.
- Forecasts catch a week that speeds up days earlier, using the last day’s pace when it’s faster.
- New alerts: tight windows, someone outside the team using a shared login, subscriptions with no reading (and how to fix), and leftover records of reinstalled machines.
- Projects group better: worktrees and subfolders count with their repository.
- Faster runs on long Claude histories, and safer state recovery.
Mac app polish.
- Clicking a problem chip shows just the affected machines in Usage.
- Usage tab columns line up cleanly.
A redesigned Mac app.
- Opens on one line that answers “am I OK?”: what’s out and when it’s back, what runs out and when, or where you have the most room.
- One row per subscription, with details on click.
- Three tabs: Limits, Usage, Projects. The menu bar ring can show percent left, time to reset, or the ring alone.
- Color only means a problem: red out, orange will run out, yellow tight.
- Also covers 0.3.2, which was tagged but never published.
Projects grouped by repository.
- A project is now a git repository, with its subfolders and worktrees counted in.
- Machines that stopped updating themselves are flagged.
- Mac app: smoother tab switching, whole-million token counts, a single quiet line for subscriptions without a reading.
AI Usage for the Mac menu bar.
- A native menu bar app (macOS 14+) installed by the same one-line installer.
- The menu bar shows the percent left of your tightest window.
- The app updates itself along with the command-line tool.
A clearer README and a sturdier codebase.
- New README with highlights, a quick start, and pictures for every section.
- Internal cleanup; no change in what you see.
Know why something is missing.
- When Claude’s quota can’t be read, it says why and what to update.
- The team sees why a machine isn’t updating itself, and since when.
- See a made-up team’s report on your own machine: demo reports you can open with ai-usage report --from.
- From this release on, every install updates itself within about 15 minutes.
Shares that add up.
- The share view shows each machine’s part of each subscription, adding up to 100%.
Fresh Claude readings.
- ai-usage now has Claude Code refresh its usage numbers (no tokens spent), so Claude quota stays current.
- It only does so for folders you used in the last hour, so idle logins are left alone.
A status view for every machine.
- Press s (or use --devices) to see each machine’s version, last report, tools, and tokens.
- The table header stays put while you scroll.
- Clearer “runs out” times on forecasts.
Reliable self-updates.
- Checks for a new release at every scheduled run, without hitting GitHub’s API limits.
- Colorful, grouped help text.
- Teammates on older versions still show up, with unknowns marked instead of zeros.
The redesigned report.
- ATTENTION at the top, only when something’s wrong.
- Subscriptions grouped by tool, with a forecast to the reset.
- A matrix of every machine against every subscription.
- An interactive terminal view, and nicknames for accounts across the team (ai-usage alias).
Forecasts and a friendlier first run.
- Each quota window is forecast to its reset.
- A short guide prints under your first report.
- Claude desktop app agent-mode sessions are counted.
- The installer puts ai-usage on your PATH and never overwrites other tools.
Small fix.
- A tool you’re not logged in to and never used is no longer reported as a problem.
Names and containers.
- Name each machine in the team; Macs go by their local host name.
- Run the collector inside containers.
- Tools installed via npm are found by scheduled runs.
Mac scheduling.
- On macOS, scheduled runs use a launch agent (launchd) instead of cron.
First release.
- One binary for macOS, Linux, and Windows that reads Claude Code, Codex, Grok, and Hermes usage every 15 minutes.
- Team view through a small relay that sees numbers, not names (encrypted and signed).
- One-line installers.
Not installed yet?
curl -fsSL https:/