Agent Usage

Monitor Claude and Codex plan limits in a VS Code Explorer panel and the status bar. Choose either provider or both, select the account/profile each uses, and hide the status summaries when you want a quieter editor.

Display and controls

The Agent Usage panel groups limits by provider:

• Claude: current session, all-model weekly quota, and model-specific limits when reported.
• Codex: only the main account’s Weekly limit, with its reset time. Spark/model-specific buckets and shorter windows are omitted from both the panel and status bar.
• Percentages, progress bars, reset times, and an Updated timestamp for each provider.
• Independent errors: an unavailable or rate-limited provider does not hide the other provider's usage. Previously fetched values keep their timestamp when a refresh fails.

The panel header has Refresh, Open Usage Page, and a settings gear. The gear opens:

1. Providers to monitor: Claude, Codex, both, or none.
2. Show/Hide status bar usage: toggles the bottom-right summaries.
3. Claude profile: selects a Claude config directory.
4. Codex home: selects a Codex home directory.
5. All usage settings: refresh interval, warning/error thresholds, and Codex executable path.

Claude uses a warm terracotta accent; Codex uses soft mint, with accessible variants for light and high-contrast themes. The colors apply to headings, progress bars, and status summaries; warning/error thresholds still take precedence. Customize agentUsage.claude and agentUsage.codex through VS Code's workbench.colorCustomizations. The two status items sit together and use their respective Claude and Codex logos. Codex also retains its name. Hover for profile and reset details. Clicking a status item opens that provider's usage page. The browser's logged-in account can differ from the locally monitored account.

Install and update

The Marketplace identity is planken.agent-usage, displayed as Agent Usage. This is a new extension identity: uninstall Claude Plan Usage (planken.claude-plan-usage) before installing it to avoid duplicate polling and conflicting views. Existing agentUsageBar settings and legacy claudeUsageBar preferences are retained. The old listing will not automatically upgrade to this extension.

From source:

git clone https://github.com/JPlanken/agent-usage-bar.git
cd agent-usage-bar
npm ci
npm test
npm run install-vscode  # macOS: packages and installs in Visual Studio Code

Use npm run install-local on systems where code is on PATH. Then run Developer: Reload Window in VS Code. The package is agent-usage.vsix.

Profiles and login

Claude

Choose the directory passed to CLAUDE_CONFIG_DIR, not the executable or a project folder. For a personal profile:

"agentUsageBar.claude.configDirectory": "~/.claude-personal"

An empty setting uses CLAUDE_CONFIG_DIR, then ~/.claude. On macOS, custom profiles select the corresponding hashed Keychain service. The fallback credentials file stays inside the same profile. Missing credentials never cause a fallback to a different account.

Sign in or refresh an expired login using the matching profile:

CLAUDE_CONFIG_DIR="$HOME/.claude-personal" claude

Codex

Install the Codex CLI and sign in with ChatGPT. The extension starts a short-lived local codex app-server --stdio, initializes its protocol, reads account information and rate limits, and closes the process. It never starts a conversation or makes a model request.

"agentUsageBar.codex.home": "~/.codex",
"agentUsageBar.codex.executablePath": "/opt/homebrew/bin/codex"

An empty home setting uses CODEX_HOME, then ~/.codex. The executable defaults to codex on the editor's PATH. Set its absolute path if VS Code cannot find it. Sign in to a custom home with:

CODEX_HOME="$HOME/.codex-personal" codex login

Codex must support account/rateLimits/read; verified with CLI 0.154.0. API-key billing does not expose ChatGPT plan quotas and produces an explanatory message. The weekly percentage and reset time come from the main account bucket. If no weekly window is reported, the extension says so instead of substituting another limit. This is a plan-limit monitor, not an API spending dashboard.

Protocol reference: Codex App Server.

Settings

Existing claudeUsageBar.* preferences remain a fallback until the corresponding agentUsageBar.* value is explicitly set. Existing command IDs and the panel ID are retained as compatibility aliases, preserving keybindings and panel placement. Changing a profile clears its previous usage immediately and ignores late responses. Disabling a provider cancels its current request and stops polling it. Display-only changes retain timestamps and do not fetch usage.

Implementation

Claude uses its existing OAuth usage endpoint, which is undocumented and may change. HTTP 429 pauses Claude polling for 15 minutes. Codex uses the documented local account interface. Credentials and raw account responses are not logged. No credentials are bundled in the extension. Endpoint results are not persisted by the extension.

npm test
npm run package
npx vsce ls --no-dependencies

Publishing

The display name is Agent Usage, package name agent-usage, and publisher planken. Version 0.5.0 is the first release under the new identity. Publish it as a new extension in the publisher portal; do not upload it as an update to the old Claude-only listing.

• Manual: upload agent-usage.vsix at the publisher portal.
• Automated: the release workflow publishes v* tags using VSCE_PAT, with optional Open VSX publishing via OVSX_PAT. A main-branch push only builds and tests.
• Credentials remain in the existing Doppler project claude-usage-bar/prd; renaming the source repository does not migrate that secret store.

To prepare a release, update the version and changelog, run tests and packaging, then publish through the chosen channel. Local installation does not publish a Marketplace update.