Agent Usage Bar

Shows how much of your Claude Code and Codex plan is left, in the VS Code status bar.

Both numbers come from the account rather than from anything counted locally, so usage you spent on another machine, in a terminal, or in another editor still shows up here.

What it shows

One status bar item per provider, each with its own monochrome glyph:

The item turns yellow past the warning threshold and red past the error threshold, both measured on the percentage used whichever way you display it. It also turns red, with a reason, whenever a provider reports the account as stopped — a spend limit or a hard rate limit — however low the percentage happens to be.

Hover for a tooltip with a themed bar per window — filled to the percentage and colored by the same thresholds as the item — the plan name, exact reset times, the pace, any credit balance, the reason the last refresh failed if one did, and links to refresh or to open the settings. Click either item for a menu that toggles a provider, refreshes, or opens the settings.

Pace

Beside each window's reset time, the tooltip says where that window is heading:

Only the 5-hour window is forecast, because it opens on your first message — the time it has been open is time spent working. The weekly window opens on a calendar anchor and runs through nights and days off, so extrapolating across it would read a strong Monday as a limit blown by Thursday; it says how much of the week has gone instead, to read against the percentage above it.

Nothing is stated until a window has been open long enough for its percentage to be a rate rather than rounding, and agentUsageBar.showPace turns the line off.

One reading for every window

Every VS Code window runs its own copy of an extension, so six open windows normally means six of everything: six timers, six requests, and six items that disagree with each other for a few seconds after each one lands.

This extension does not work that way. The windows of a profile share one reading and one schedule:

• Six windows cost about what one does. Only one window actually asks; the rest read the answer.
• All of them show the same number, including the ones that never made a request.
• No window has a timer of its own. The refresh interval belongs to the machine, so closing the window that happened to be reading costs one cycle rather than leaving the others stalled.
• A rate limit is honoured everywhere at once, and every item counts the same wait down.

There is no leader and nothing is elected, so there is nothing to get stuck. See Sharing between windows for how it works.

Requirements

• VS Code 1.100.0 or newer, desktop.
• For the Claude item: Claude Code installed and signed in.
• For the Codex item: Codex installed and signed in, either through the desktop app or as the standalone CLI. The extension finds whichever you have, including the copy the Codex IDE extension ships.

Neither is required for the other. A provider that is not installed or not signed in says so in its tooltip; switch it off in the settings and its item disappears.

Install

From the Marketplace, or from a .vsix:

1. Download or build a .vsix (see CONTRIBUTING.md).
2. Run Extensions: Install from VSIX... in VS Code and pick the file.

Settings

Run Agent Usage Bar: Open settings, or click either status bar item and pick Open settings.

In compact mode the item shows the shortest window, unless a longer one is the reason the item is colored — a highlighted status bar always explains itself.

Dates and times follow VS Code's display language when the locale setting is empty, which is not the same as the regional settings your operating system holds — VS Code in English shows US dates on a machine set to anything else. Write a language tag such as en-GB, de-DE, or sr-Latn-RS to say which one you want, and append -u-hc-h23 for a 24-hour clock or -u-hc-h12 for a 12-hour one, as in en-US-u-hc-h23. A tag VS Code cannot resolve is ignored rather than shown.

Each provider is drawn with its own monochrome mark. Set a label if you would rather see your own text; it accepts a plain string or a codicon reference such as $(sparkle), and is collapsed to a single line and cut to 24 characters so a hand-edited value cannot stretch the status bar.

Troubleshooting

Every failure keeps the last good numbers on screen rather than blanking the item, so the tooltip is where the reason lives.

A macOS keychain prompt was declined. That is respected rather than retried: the read is not attempted again for half an hour, so declining does not turn into a prompt every five minutes. Run Agent Usage Bar: Refresh usage to ask again immediately.

The numbers look old. A history icon and a note in the tooltip appear once a reading is more than ten minutes old, so a stale number never passes as current. Refresh from the menu to force a read that ignores the usual floor.

Nothing appears at all in a Remote-SSH, WSL, or dev container window. The extension runs on the machine your editor runs on, which is where both agents keep their sign-ins. See Platform scope.

Data access

This extension reads a credential, so the boundary is worth stating exactly. Usage is a property of the account rather than of this machine, so both providers are asked about the account instead of a local scoreboard being counted up.

Codex

The extension starts codex app-server and asks it over JSON-RPC on stdin and stdout. Codex holds its own credentials and refreshes them itself, so this extension never reads or handles a Codex token: ~/.codex/auth.json stays outside the boundary, and npm run audit:bundle fails the build if that path appears in the shipped bundle. When the CLI cannot be located or is signed out, the item reports that rather than guessing from local files.

Claude Code

The extension reads the token Claude Code stores, spends it on one request, and drops it. That request goes to https://api.anthropic.com/api/oauth/usage, the same endpoint the official Claude Code extension uses for this.

The token is never logged, cached, or written back — not to the shared state, not to settings, not to the extension's secret storage. Keeping a copy would trade one file read every five minutes for a second place a credential lives: one that goes stale when Claude Code rotates the token, and that would have to be invalidated on sign-out.

It is also never refreshed, deliberately. A refresh rotates the stored token, so racing Claude Code for it would sign Claude Code itself out. When the token is expired or rejected, the extension says so and leaves the renewing to Claude Code.

Where the token lives depends on the platform:

Reading the macOS keychain

The keychain is read through the tool macOS ships for it: /usr/bin/security find-generic-password, started directly at that absolute path with its arguments as a list, so nothing on PATH can stand in for it and no argument can be read as a command. It only reads. No keychain verb in this extension changes what is stored, and npm run audit:bundle fails the build if one ever appears.

The file is tried first even on macOS, because it is the cheaper question and Claude Code falls back to it where the keychain is not available. An ordinary macOS read therefore starts one short-lived process, and an ordinary read anywhere else starts none.

If macOS puts a prompt in front of that read, the answer is respected rather than worked around:

security exits with the status it was given, so these are told apart by its exit code rather than guessed at. Only one window ever asks, because only one window does the reading.

Agent transcripts

~/.codex/sessions and ~/.claude/projects are watched purely as an "an agent just ran" signal: only the fact that a .jsonl file changed is used, and once the writes settle a refresh is requested. The transcripts themselves are never opened.

Codex also pushes an account/rateLimits/updated notification, but that only arrives while its app server is running, and this extension stops that process ten minutes after the window last read rather than keeping a child process resident for a signal. The watch covers the rest of the time, and is what starts a fresh app server when an answer is wanted again.

Every automatic read sits behind a floor of thirty seconds per provider, whichever trigger asked for it: a single long turn writes its transcript in bursts, and the percentages it moves are not worth a request each. A refresh you ask for from the menu ignores the floor.

Sharing between windows

Each reading is stored in the extension's own state, which VS Code shares between the windows of a profile, together with the moment the read was started. A window that finds a reading younger than the floor displays it rather than asking again, and a rate-limit wait is honoured by all of them at once.

The background interval is the machine's rather than each window's: whichever window notices it has run out does the reading, so a window closed mid-read costs one cycle rather than a stalled status bar. There is no leader and nothing to elect — the window that read last simply keeps a few seconds of head start, which is enough for the reading to settle on one of them. Two windows arriving in the same instant both write their claim and then re-read it before spending a request, so all but one stand down. That is not a lock and cannot be one; on a rare tie the cost is a second request, not a wrong number.

What is stored, and what never leaves

That one endpoint is the only network target in the extension. npm run audit:bundle pins the full allowlist, so a second URL, a shell execution, or any filesystem write fails the build. The extension opens files only to parse them and writes no files of its own.

It persists exactly two things, both through VS Code's own APIs:

• Your settings, when you toggle a provider from the menu.
• The last usage reading, so the other windows can show it — percentages, reset times, window lengths, and the plan name.

Neither carries a token, a prompt, or any file content. There is no telemetry, no runtime dependency, no custom credential path, and no custom update mechanism. No prompt, code, or file content ever leaves the machine.

Resets, staleness, and rate limits

A reading is a point-in-time snapshot, so a percentage can predate a window reset. The extension detects that from the recorded reset time, shows 0% behind a ~ marker, and suppresses the warning color rather than presenting an unconfirmed number as current. A reading older than ten minutes is marked with its age in the tooltip, and a failed refresh keeps the last good numbers rather than blanking the item.

When the Claude usage service rate limits a request, the Retry-After it sends is honoured for every trigger alike — the background poll, local agent activity, and the menu — and the tooltip names the moment the read resumes instead of asking again. A refusal that names no window is held for a minute, and one naming more than an hour is asked again at the hour: a wait longer than the longest refresh interval is indistinguishable from a stall, and one long enough to overflow a timer is worse than that.

Platform scope

Version 0.1.0 is developed and hand-tested on desktop VS Code on Windows. Both other desktop platforms are implemented rather than assumed: the Codex install layouts and the macOS keychain read are covered by tests that run on all three CI runners, and the file watcher is exercised against the real recursive implementation on each. What no runner can supply is an actual Codex install or an actual Claude Code sign-in, so what remains unconfirmed on macOS and Linux is whether those live in the places this looks — not whether looking there works.

The extension runs on the machine your editor is running on, which is where both agents keep their sign-ins. In a Remote-SSH, WSL, or dev container window it therefore reports the usage of the local account. If your agents run on the remote side, their usage is not what you will see.

There is no web build. It reads local files and starts a local process, neither of which exists in a browser.

Contributing

Setup, the architecture, the scripts, and how the provider glyphs are built are all in CONTRIBUTING.md. Security reports go through SECURITY.md.

License and trademarks

MIT; see LICENSE.

The icon font in assets/agent-usage-bar.woff was created specifically for this project and does not include third-party font files.

Claude and Anthropic are trademarks of Anthropic. Codex and OpenAI are trademarks of OpenAI. The monochrome provider glyphs are used solely to identify the services whose usage is being displayed.

This project is independent and is not affiliated with, endorsed by, or sponsored by Anthropic or OpenAI.

Either provider glyph can be replaced with custom text or a VS Code codicon through the agentUsageBar.claude.label and agentUsageBar.codex.label settings.