agent-usage
Windows · one file · no runtime
A desktop panel and a taskbar badge for your Claude Code and Codex subscription limits. It gets the numbers from the tools you already installed — no browser session, no credentials read, no tokens spent.
Intel and AMD. On an Arm device, take the arm64 build instead — or the zips and checksums from the release page. On a Mac or a Linux box, there is a CLI that feeds your menu bar the same readings.
The pale mark on each bar is where an even burn would have reached by now. Fill short of it is spare; fill past it is a window that runs out before it resets.
Where the number comes from
Every tool that shows this number has to get it from somewhere. Most reach for a browser session. This one runs a command, or reads a file that command wrote.
$ claude -p "/usage" --output-format json { "num_turns": 0, "total_cost_usd": 0, "result": "Current session: 4% used · resets Sat, 3am Current week (all models): 94% used …" }
Costs nothing
/usage is handled locally by the CLI. It reports no turns and no cost,
so polling every thirty seconds never touches your limits.
Nothing to steal
The CLI holds the token and refreshes it. The widget reads stdout. There is no credentials file to parse and no cookie to borrow.
Fails loudly
The CLI's text layout is not a contract. If it changes, the panel says it could not parse rather than showing a figure it guessed.
And Codex
Codex has no /usage to ask. But it writes the rate limits the API returns
into its own session transcript on every turn, so the figure is already sitting in
~/.codex/sessions — no process to launch, nothing to authenticate against.
Cheaper than free
A Claude account costs a CLI startup, about two and a half seconds. A Codex account costs one read of the tail of a file.
Honestly stale
Codex only records limits while you use Codex. So the panel says how old the reading is — measured 3h ago — instead of implying it is live.
Knows when to shut up
Leave Codex alone for a week and last week's 93% used describes a week that is over. That reads stale, never as a live 93%.
More than one login
Claude Code keeps each account in its own config directory. Point the widget at them and it polls all of them at once — separate processes, so two accounts take about as long as one.
Set up a second profile
$env:CLAUDE_CONFIG_DIR = "$HOME\.claude-personal" claude auth login
Then list it
"accounts": [
{ "label": "work" },
{ "label": "personal",
"configDir": "C:\\Users\\you\\.claude-personal" }
]
The panel grows a block per account. The taskbar shows the worst number across all of them, because that is the one that decides when you stop working.
In the taskbar and tray
Two things can stop you working: the session window, which resets in hours, and the weekly one, which locks you out for days. Both belong in the icon, and there is only so much room — so detail is dropped in a fixed order as accounts are added.
| Accounts | What the icon shows |
|---|---|
| 1 | Week digits, session as a strip along the top edge |
| 2 | A bar pair each — session above week, matching the panel's rows |
| 3–4 | One bar each, week only |
| 5+ | Digits for the worst week |
Colour always means severity, never identity — a red bar tells you a limit is nearly gone, not which account it belongs to. Accounts are told apart by position, in config order, which makes the panel the icon's legend. If you only care about one number, Icon shows in the right-click menu lists the limits your CLI actually reported and pins the icon to one of them.
macOS and Linux
The widget is raw Win32 and stays that way. But the half that reads your usage has no
Windows in it at all, so it also ships as agent-usage — one self-contained
binary that prints the same readings wherever you run it.
$ agent-usage work · claude · max session 1% resets in 4h 16m week 0% resets Aug 22, 11:59am codex · codex · plus (measured 3h ago) session 12% resets in 1h 4m week 3% resets Aug 18, 2pm $ agent-usage --brief work 0% · codex 3%
macOS
A plugin ships in the repo. Drop it in, chmod +x, done — no jq, no python,
no runtime, because the binary does the formatting.
Linux
A waybar module with tooltips and threshold colours, and one-liners for tmux status bars and shell prompts.
Anything else
--json, and it is a contractA versioned snapshot with every window, reset moment and reading age. Fields get added, never repurposed.
One detail worth knowing if you build on it: a percentage can come back null, and that is information rather than a gap. It means the limit cannot honestly produce a proportion — a count with no ceiling, or a window that has already reset. Drawing it as zero would turn I don't know into you have used none of it.
Install
The widget shells out to it. If claude auth status works in a terminal,
you are set. Codex accounts need nothing at all beyond a ~/.codex you
have used at least once.
One self-contained file, about 2.8 MB. Nothing to install and no .NET runtime to
add. It is unsigned, so SmartScreen asks once — every release publishes a
SHA256SUMS.txt you can check against.
Edit accounts… opens the config file, Reload config applies it. Drag the panel anywhere, on any monitor; it remembers. Minimise sends it to the taskbar, close sends it to the tray, and exit lives in the tray menu.
Before you download
/usage text nor Codex's transcript records are a
published API. A change breaks the parser, and both fail to an error rather than to a
number.
checkForUpdates to false and it
makes no network requests at all.