Agent Usage Bar

See Claude Code, Codex, and Antigravity usage, reset times, and pace directly in the VS Code status bar.

Usage is read at the account level, not inferred from local activity, so activity from other machines, terminals, and editors is included.

No configuration is required. All three providers are enabled by default, an item appears for each agent found on this machine, and readings refresh automatically. See Which items appear.

What it shows

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

Example	Meaning
5h 42% (2h 15m)	42% of the 5-hour window used, which refills in 2h 15m.
5h 42% (2h 15m) · 7d 18% (4d 6h)	Both windows, in full display mode.
7d Fable 86% (4d 6h)	A weekly limit for one model. Plans that carry these get a bar per limit in the tooltip; the status bar names one only while it is the window driving the color.
5h Gemini 42% (2h 15m)	An Antigravity window. Antigravity keeps a 5-hour and a weekly limit for each model group, so the status bar shows the most used group of each window and names it; the tooltip has a bar for every one.
5h Claude and GPT 34% (3h 2m) · 5h Gemini $(circle-slash) 1h 12m	The Gemini group is spent and refills in 1h 12m. A spent group hands the item to the most used group that still has allowance and keeps only its reset time. If every group is spent, the one that refills first is shown as the percentage.
5h 58% left (2h 15m)	The same reading with percentageMode set to remaining.
~5h 0%	The window reset since this reading; 0% is assumed, not read, and no color is raised on it.
$(history) 5h 42% (2h 15m)	The reading is more than ten minutes old.
--	No reading yet. The tooltip says why.

By default, the item turns yellow when usage reaches the warning threshold and red at the error threshold. Set agentUsageBar.warnWhen to overPace to show yellow only when the warning threshold is reached ahead of schedule—for example, 80% used before 80% of the window has passed. The red threshold always applies. Colors use the percentage used, regardless of the selected display mode. The item also turns red when a provider reports that the account is stopped by a spend limit or hard rate limit, even when the percentage is low; the tooltip states the reason.

Hover to see the plan name, a themed progress bar for each window, exact reset times, pace, any credit balance, Codex reset credits and Claude limit resets with the date the soonest one expires, and the last refresh error. The bars use the same warning and error thresholds as the status item. The tooltip also links to refresh and settings. Click any status item to toggle a provider, refresh usage, or open settings.

Pace

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

Line	Meaning
At this pace, runs out ~12:20	The 5-hour window hits the limit before it refills.
At this pace, ~34% by reset	It does not, and this is where it ends up instead.
68% of the week gone	How much of the weekly window has elapsed.

Only the 5-hour window is forecast. It opens on your first message, so its elapsed time roughly follows working time. The weekly window starts from a calendar anchor and continues through nights and days off. Forecasting from a busy Monday could therefore predict a limit by Thursday even when the rest of the week is quiet. For that window, the tooltip shows elapsed time instead of a forecast.

The weekly bar also carries a mark standing where that elapsed percentage falls, so a glance says whether spending is ahead of the week or behind it. The mark is left off where it would say nothing: under the bar's rounded ends, or right beside the edge of the fill, which is the same comparison.

Pace remains hidden until the window has been open for fifteen minutes, and the 5-hour forecast also requires at least three percent usage. These minimums prevent rounded early values from being presented as a meaningful rate. Set agentUsageBar.showPace to false to hide pace information.

warnWhen works even when showPace is off. If a window is too new to compare, the warning threshold applies normally.

Daily activity

Under the windows, the tooltip draws the last thirty days as one bar per day: the busier the day, the taller and darker the bar; a day the agent was not used is a flat mark on the baseline. Each day is placed in one of five steps relative to the busiest day in view, so a bar says which band a day fell in — twice the height is not twice the work.

The days are counted from what the agents already recorded on this machine, so the strip is complete on the first hover and includes work done outside VS Code. For Claude Code and Codex that is their session transcripts. Antigravity keeps each conversation in a database of its own, so its days are asked of the Antigravity CLI instead. Only recorded numbers and times are taken; see Data access.

Each provider is measured in the unit it records, and the units are never compared:

Provider	What a day counts
Codex	Percent of the weekly limit spent that day. Codex records the account's own percentages, so a day is exact.
Claude Code	Tokens written that day. Claude Code records tokens, not percentages, so its strip shows relative activity only.
Antigravity	Input and output tokens of that day's model calls, which is relative activity only, like Claude Code's. A conversation is counted once it has been quiet for a minute, so today's bar trails a conversation in progress.

A day from before the first scan is drawn like an unused one. That matters for Claude Code, which deletes its transcripts after cleanupPeriodDays (thirty days by default): the oldest cells may stay empty however much work they held. Once a day has been counted it is kept, so the strip fills in from there. Nothing is drawn when no day in view has activity.

One reading for every window

Every VS Code window runs its own copy of an extension. Without coordination, six open windows could make the same request six times and briefly show different readings.

The windows in one VS Code profile instead share the latest reading and the network refresh 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 an independent network refresh schedule. Each window still updates its own countdown display, but the next account read is due at one shared time. If the reading window closes, another window can retry after the shared minimum delay instead of waiting for a full refresh interval.
• A rate limit is honoured everywhere at once, and every item counts the same wait down.

VS Code shares the extension state between windows in the same profile. That state contains the latest result and the time its read began. A window that finds a recent shared result displays it instead of requesting another one. When the configured interval expires, whichever window notices first can attempt the next read.

There is no elected leader. The window that completed the previous read gets a short head start, which usually keeps subsequent reads in the same window. When several windows become due together, they write a shared claim, wait briefly for it to propagate, and check it again before making a request. This is coordination through VS Code state, not an atomic lock. A rare tie can produce one duplicate request, but cannot replace a newer published reading with an older one.

Requirements

• VS Code 1.100.0 or newer, desktop.
• For the Claude item: Claude Code installed and signed in, either as the standalone CLI or as the official Claude Code extension, which ships its own copy of it. Signing in to the Claude desktop app is not enough on its own; it keeps its sign-in somewhere else entirely.
• 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.
• For the Antigravity item: the Antigravity CLI (agy) installed and signed in. The official Antigravity extension for VS Code installs it to ~/.gemini/bin on first run, and the standalone CLI installer puts it in the same place.

None is required for the others.

Which items appear

An enabled provider is not always a visible one. A provider's enabled setting means "show this agent's usage when the agent is found on this machine". With all three enabled and one agent installed, there is one item.

The provider is	Its agent is	The item
off	found or not	hidden
on	found	shown
on	not found	hidden, unless every provider is on and no agent is found

The exception covers a fresh install on a machine with no agent: with every provider still on and no agent found, all three items stay, so the tooltips can say what to install. While any provider is off, a missing agent is simply hidden, so switching off the only agent that was found leaves the status bar empty rather than bringing the others back. The menu stays reachable through Agent Usage Bar: Open menu.

An agent counts as not found only when two things are both true. There is nothing to run or read for it, and its own data directory does not exist: ~/.claude, ~/.codex, or ~/.gemini/antigravity. An agent that is installed but signed out, or one the extension cannot start, keeps its item and says why in the tooltip.

Nothing about this is remembered. Every read asks again, so an agent installed later gets its item at the next read, without a reload. The menu shows a hidden one as Not found on this machine.

Install

Search for Agent Usage Bar in the Extensions view, or install it from the VS Code Marketplace or Open VSX.

To install a .vsix by hand instead:

1. Download or build one (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 any status bar item and pick Open settings.

Setting	Default	Purpose
agentUsageBar.displayMode	compact	compact shows the shortest active window; full shows both.
agentUsageBar.percentageMode	used	Show the percentage used or the percentage remaining.
agentUsageBar.showPace	true	Show where each window is heading.
agentUsageBar.showHistory	true	Show the thirty-day activity strip in the tooltip.
agentUsageBar.warningThreshold	80	Warning color threshold based on used percentage.
agentUsageBar.errorThreshold	95	Error color threshold; never falls below warning.
agentUsageBar.warnWhen	threshold	overPace warns only when usage reaches the threshold ahead of schedule.
agentUsageBar.claude.enabled	true	Show Claude Code usage while Claude Code is found; see Which items appear.
agentUsageBar.codex.enabled	true	Show Codex usage while Codex is found.
agentUsageBar.antigravity.enabled	true	Show Antigravity usage while Antigravity is found.
agentUsageBar.claude.label	""	Text to show instead of the Claude mark.
agentUsageBar.codex.label	""	Text to show instead of the Codex mark.
agentUsageBar.antigravity.label	""	Text to show instead of the Antigravity mark.
agentUsageBar.locale	""	Language tag for dates and times; empty follows VS Code.
agentUsageBar.refreshIntervalSeconds	300	Background refresh interval, clamped to 30–3600.

In compact mode, the item normally shows the shortest window. If a longer window triggers a warning or error color, it is shown instead so the highlighted state has a visible cause. A warning suppressed by overPace does not make the item switch windows.

When the locale setting is empty, dates and times follow VS Code's display language rather than the operating system's regional settings. For example, VS Code in English uses US-style dates even when the operating system uses another region. Set a language tag such as en-GB, de-DE, or sr-Latn-RS to choose the format explicitly. Add -u-hc-h23 for a 24-hour clock or -u-hc-h12 for a 12-hour clock, as in en-US-u-hc-h23. An unsupported tag is ignored.

Each provider has its own monochrome mark. Set a label to replace it with a plain string or a codicon reference such as $(sparkle). The value is collapsed to one line and limited to 24 characters so a hand-edited setting cannot stretch the status bar.

Troubleshooting

After a refresh failure, the last good reading remains visible instead of being replaced with an empty value. The tooltip states what happened and, when an action can help, shows it on a separate line under a lightbulb.

The tooltip says	What it means
No Claude Code sign-in was found	Sign in to the Claude Code CLI or extension; the Claude desktop app keeps a store of its own.
The Claude Code sign-in has expired	Run Claude Code; it renews its own token. This extension deliberately will not.
Claude Code is no longer signed in	The service rejected the stored token. Sign in to Claude Code again.
Rate limited, retrying at …	No action is required. Reading resumes at the displayed time.
The usage service could not be reached	Check the network or proxy. The last reading remains visible with its age.
Codex reported no usage windows	Sign in to Codex, or the account has no windows to report. Signing in is picked up on the next read.
The Codex CLI could not be started	Codex was not found in a supported local installation; see Platform scope.
The Codex app server timed out	The CLI stopped responding. The next read starts a fresh one automatically.
Antigravity could not be started	The agy CLI was not found in ~/.gemini/bin. Install the CLI, or switch the item off.
Antigravity is not signed in	Sign in through the Antigravity CLI or its extension. Signing in is picked up on the next read.
Antigravity did not answer in time	The CLI started but did not come up within twenty seconds. The next read starts a fresh one.

An item is missing. Open the menu from another item, or run Agent Usage Bar: Open menu. A provider shown as Not found on this machine is enabled, but had nothing to run or read and no data directory; see Which items appear. Installing or signing in to the agent brings the item back at the next read, and Refresh usage asks at once.

Rate limited. A Retry-After response pauses background polling, refreshes triggered by local agent activity, and menu refreshes alike. The tooltip shows when reading will resume. A response without a delay pauses reads for one minute. A delay longer than one hour is capped at one hour so an excessive or invalid value cannot leave the extension stalled beyond its longest refresh interval.

A macOS keychain prompt was declined. The extension waits half an hour before trying again, preventing a new prompt on every five-minute refresh. Run Agent Usage Bar: Refresh usage to retry immediately.

The numbers look old. A history icon and tooltip note appear when a reading is more than ten minutes old. Refresh from the menu to request a new reading without the normal minimum interval.

Nothing appears in a Remote-SSH, WSL, or dev container window. The extension runs beside the local VS Code user interface and reads local agent sign-ins. See Platform scope.

Data access

Account usage cannot be calculated reliably from activity on one machine, so the extension asks each provider for the account-level reading. The credential boundary for those requests is described below.

Codex

The extension starts codex app-server and requests usage over JSON-RPC through stdin and stdout. Codex manages and refreshes its own credentials, so this extension never reads or handles a Codex token. ~/.codex/auth.json remains outside the boundary, and npm run audit:bundle fails if that path appears in the shipped bundle. If the CLI cannot be found or is signed out, the status item reports that state instead of inferring usage from local files.

Antigravity

For each reading, the extension starts the Antigravity CLI as agy --hub, asks it for the account's limits over HTTP on the loopback address, and stops it again. Antigravity manages and refreshes its own Google sign-in, so this extension never reads or handles a Google token, and it makes no request to a Google service itself.

The hub is started on a free local port with an access token generated for that one start. Antigravity's own extension runs a hub per VS Code window in the same way; this extension does not look for those or read their tokens. It asks its own hub three questions: the quota summary, the plan name, and, only when no limits came back, whether the CLI is signed in. The answer carrying the plan name also names the account holder; only the plan name is taken out of it.

A hub is stopped after every reading instead of being kept. A running hub holds well over a hundred megabytes and answers a repeated question from its own cache, so one kept between readings would cost memory and return a reading of unknown age. Starting one takes about two seconds.

The hub is asked to write no log file. On each start it still leaves an empty crash marker under ~/.gemini/antigravity/crashes, which a later start cleans up, and it opens Antigravity's own state files beside that directory. Those writes are Antigravity's, not this extension's.

This interface is not documented by Google. It is the one Antigravity's own extension uses, and it can change with any Antigravity update. When it does, the item reports that no reading is available and the other providers are unaffected.

Antigravity conversations

The daily activity strip has the hub read your conversations, and takes two things out of them. A conversation is a SQLite database under ~/.gemini/antigravity/conversations that only Antigravity's own program can read, so the extension starts a hub and asks it two questions per conversation:

Question	What is taken
The model calls of the conversation	The input and output token counts of each call, and which step it belongs to. Cached input is left out.
The steps of the conversation	The time each step was made. This answer also carries the conversation itself: your prompts, the replies, and the commands that were run.

Nothing but a step's time is read out of the second answer, and no prompt, reply, command, or file content is kept, stored, logged, or shown. What outlives the scan is one number per calendar day.

A conversation in use is not opened. Opening one that still has unsaved changes makes SQLite move them into the database file, which would change a file Antigravity is working on. A conversation is therefore read only once it has been quiet for a minute and its write-ahead log holds nothing newer than the database. One that still has such a log after half an hour without a write is treated as left behind and read anyway. Reading a conversation does recreate the two empty companion files SQLite keeps beside a database; the database itself is not written.

A hub is started for a scan only when a conversation that can be read has changed since this window last read it, and at most once in ten minutes across all windows. What a window has read it keeps in memory. A newly opened window therefore reads the conversations of the last few days once, unless none was written since the last scan; then it shows the stored days and starts no hub. The very first scan reads every conversation of the last sixty days. Setting agentUsageBar.showHistory to false stops these scans entirely.

Claude Code

The extension reads the token stored by Claude Code, uses it for one request, and discards it. The request goes to https://api.anthropic.com/api/oauth/usage, the same endpoint used by the official Claude Code extension for usage data.

The plan name comes from a second request, made once per sign-in. After the first successful reading the token also goes to https://api.anthropic.com/api/oauth/profile, which the official Claude Code extension reads for account details. The sign-in stores only an internal plan identifier, which can stay the same when a plan is renamed; the profile carries the name claude.ai shows. That answer also names the account holder and organization; only the plan name is taken out of it. The request is repeated when Claude Code renews its token, and a failed one leaves the plan as the sign-in states it.

The request identifies itself as the Claude Code CLI. It carries the user agent claude-cli/<version> (external, cli) because the service returns banked limit resets, the free resets shown under Settings > Usage on claude.ai, only to that client at or above a minimum version. The version is a pinned published release, or the newest Claude Code installed on this machine when that is newer: the official extension's bundled CLI, or a release under ~/.local/share/claude/versions. Resets are only read and counted, never redeemed. If the service stops listing them, the credits line drops the resets and every other reading stays the same. If it refuses that request outright, the extension repeats it once without the resets query and user agent, and keeps sending the plain request for the rest of the session once that one succeeds.

The token is never logged, cached, or written back to shared state, settings, or the extension's secret storage. Caching it would create a second credential store that could become stale when Claude Code rotates the token or signs out. Reading the existing store when needed avoids that additional copy.

The extension also never refreshes the token. Refreshing can rotate the stored credential, and competing with Claude Code for that update could invalidate Claude Code's own session. When the token expires or is rejected, the extension reports it and leaves renewal to Claude Code.

Where the token lives depends on the platform:

Platform	Location
Windows, Linux	~/.claude/.credentials.json
macOS	The login keychain, under the item Claude Code created for it

The store belongs to Claude Code and is shared by the CLI and the official Claude Code extension, which includes its own copy of the CLI. Signing in through either one therefore creates the same credential. The Claude desktop app uses a separate encrypted store that this extension does not read.

Reading the macOS keychain

The extension reads the keychain with /usr/bin/security find-generic-password, using the absolute system path and a separate argument list. Nothing on PATH can replace that executable, and no argument is interpreted as a command. The operation is read-only; npm run audit:bundle fails if the bundle carries any password verb other than find-generic-password.

The credentials file is checked first on every platform because Claude Code uses it when the keychain is unavailable. A normal macOS keychain read therefore starts one short-lived process; normal reads on other platforms start none.

Normally, reading the item through security requires no authorization prompt because Claude Code's access list already permits it. A locked keychain, an item transferred from another Mac, or a manually restricted access list can still cause a prompt. The extension respects that result:

Outcome	What happens next
No such item	Checked again on the next interval without showing a prompt.
Declined, locked, or not ours	Not asked again for half an hour, so a declined prompt does not come back five minutes later.
No answer within five seconds	Abandoned, and counted as a refusal.

The extension distinguishes these outcomes through the exit code returned by security. Multi-window coordination ensures that only the window performing the account read can trigger the keychain request.

Agent transcripts

The extension watches ~/.codex/sessions and ~/.claude/projects for the fact that a .jsonl file changed, and ~/.gemini/antigravity/conversations for the fact that any file in it changed. After the writes settle, that change requests a usage refresh. Antigravity's conversation files are never opened by this extension itself; see Antigravity conversations for what its hub is asked.

The Claude Code and Codex transcripts are also read, for the daily activity strip only. They contain your prompts and your code, so what is taken out of them is worth stating exactly. Each line is parsed as JSON and one of two things is kept:

Provider	What is taken
Codex	The timestamp and used_percent of the weekly window that Codex records beside every token count.
Claude Code	The timestamp, the message id, and the input, output, and cache-creation token counts of an assistant message.

Nothing else is read out of a parsed line, and no message, prompt, file path, or file content is kept, stored, logged, or shown. The daily totals that result are numbers per calendar day, and they are the only thing derived from a transcript that outlives the scan. Setting agentUsageBar.showHistory to false stops the extension from opening these files at all; the watching described above continues, because that is what keeps the live reading current.

A first scan reads every transcript once. Later scans read only files modified since the last one, which is normally the session currently being written, and no scan runs within two minutes of another window's.

Codex also sends an account/rateLimits/updated notification while its app server is running. The extension stops an idle app server after ten minutes instead of keeping a child process alive only for that notification. It also drops one whose read produced no reading, because such an app server tends to answer the same way until it is replaced. File watching covers later activity and triggers a fresh app server when another reading is needed.

Every automatic read has a minimum interval of one minute per provider, regardless of which trigger requested it. A long agent turn can write its transcript in several bursts, and those small updates do not justify a request each. A manual menu refresh bypasses this minimum.

When the Anthropic usage endpoint refuses a read with a stated wait, that wait is honoured, by the manual refresh too. When it refuses without one, the extension waits a minute, then doubles the wait on each further refusal up to fifteen minutes, so a limit shared with other clients is not kept tripped by the retries themselves. Any answer that is not a refusal resets the wait, and windows share the count.

What is stored, and what never leaves

The Anthropic usage and profile endpoints are the extension's only remote network targets. Its one other request stays on this machine: the loopback address of the Antigravity hub it started itself. The extension opens files only for parsing and performs no direct filesystem writes.

npm run audit:bundle checks the shipped code on every build. For the member-access forms produced by the current build, it rejects node:fs members outside the explicit read-only set. It permits only spawn from node:child_process and rejects literal shell: true options, and permits only createServer from node:net, which is how a free local port is found.

The shipped text leaves two things for code review to establish. The URL allowlist can inspect only addresses written out in full; a URL assembled from parts at runtime is outside its reach. Likewise, because the program passed to spawn is resolved at runtime, the audit constrains how a process is started but cannot prove which one. The audit catches accidental violations of these promises; code review remains responsible for runtime-computed behavior.

It persists exactly three things, all 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.
• One number per calendar day per provider, for the daily activity strip, kept for sixty days.

No stored value contains a token, prompt, or file content. The extension has no telemetry, runtime dependency, custom credential path, or custom update mechanism. No prompt, source code, or file content is sent anywhere.

Platform scope

Desktop VS Code on Windows, macOS, and Linux, hand-tested on all three against real installs of all three agents. The per-platform paths are covered by tests on all three CI runners as well: the Codex install layouts, the macOS keychain read, and the file watcher against the real recursive implementation.

The extension runs on the same machine as the VS Code user interface, where the agents keep their sign-ins. In a Remote-SSH, WSL, or dev container window, it therefore reports usage for the local account. It does not read an agent sign-in that exists only on the remote side.

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. Antigravity and Google are trademarks of Google. 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, OpenAI, or Google. Any glyph can be replaced with your own text or a codicon; see Settings.