AI Agent Quota Monitor for VS Code

Complete end-user installation, distribution, privacy, and provider-integration details are included in docs/USER-GUIDE-AND-INTEGRATIONS.md.

AI Agent Quota Monitor tracks rolling consumer-subscription limits across supported AI coding agents. The current release integrates with Codex and Claude Code and is designed to accommodate additional providers in future releases. It supports ChatGPT Plus/Pro and Claude Pro/Max accounts—not organization Admin APIs or pay-as-you-go API billing.

This is an independent community extension. It is not affiliated with, endorsed by, or sponsored by OpenAI or Anthropic.

The status bar shows the most constrained active window for each provider:

$(hubot) Codex: 88% left | Claude: 95% left

The background changes to warning at 20% remaining and error at 10%. Clicking it opens a details view with every window, reset countdown, plan, freshness, and sanitized local token activity.

What this extension does not do

• It never asks for or stores OAuth tokens, API keys, browser cookies, prompts, responses, or attachments.
• It does not call private consumer endpoints.
• It does not invent a monthly token maximum. Consumer products expose rolling limits that may vary by plan, model, and demand.
• Reset Local State clears only this extension’s history. It cannot reset a provider quota.

Codex / ChatGPT setup

1. Install the official Codex CLI or OpenAI Codex VS Code extension.
2. Run AI Agent Quota Monitor: Connect Codex from the Command Palette.
3. Complete the official ChatGPT browser login if requested.

The extension locates Codex from aiTokenTracker.codexExecutablePath, an installed OpenAI extension, or PATH. It launches codex app-server, completes the documented JSON-RPC initialization, and reads account/rateLimits/read plus account/usage/read. Authentication remains owned by Codex. Live rate-limit notifications are consumed immediately; a configurable polling fallback and bounded process restart are also enabled.

If automatic discovery fails, set AI Agent Quota Monitor: Codex Executable Path to the full Codex executable path.

Claude setup and consent

1. Install and sign in to Claude Code with a Claude Pro or Max subscription.
2. Run AI Agent Quota Monitor: Enable Claude Automatic Tracking.
3. Review and approve the confirmation dialog.
4. Use Claude Code normally. Quota percentages appear after Claude completes an API response.

The command makes one intentional change to ~/.claude/settings.json: it registers a small local bridge as Claude Code’s statusLine.command. The bridge runs with VS Code’s bundled Node/Electron runtime, so a separate Node installation is not required. It writes only:

• five_hour and seven_day percentages/reset timestamps;
• context/token counters;
• session ID and collection timestamp.

If a status-line command already exists, the bridge forwards the original JSON to it and preserves its output. Existing refresh intervals below 60 seconds remain unchanged; longer or missing intervals become 60 seconds.

Run AI Agent Quota Monitor: Disable Claude Automatic Tracking to restore the previous status-line configuration. Restoration occurs only when the installed setting is unchanged; if another tool or the user edits it afterward, the extension refuses to overwrite that external change.

Claude tracking is automatic while Claude Code is running. Its account-wide percentages update after Claude API responses. When Claude Code is closed, the last values and reset countdown remain visible but become stale. New activity from claude.ai cannot be fetched in the background unless Anthropic provides a consumer usage API.

Local Claude token activity

The extension incrementally scans ~/.claude/projects/**/*.jsonl. It extracts only timestamps, message IDs, model names, and message.usage, then stores aggregate counters and byte offsets. Prompt text, responses, tool inputs, attachments, and credentials are never retained. Truncated and malformed live transcript files are handled safely.

Alerts

Each provider/window—including the 5-hour and weekly quota windows—keeps an independent alert milestone. By default, modal alerts appear at 50% and 90% used. Incremental changes between milestones update the status bar without opening a dialog. A large jump creates one summary alert and advances directly to the highest crossed milestone. A changed reset timestamp or lower usage starts a new alert cycle automatically. Choose Mute Alerts in any usage alert, or disable modal alerts in Settings, for status-bar-only tracking.

Commands

• AI Agent Quota Monitor: Connect Codex
• AI Agent Quota Monitor: Enable Claude Automatic Tracking
• AI Agent Quota Monitor: Disable Claude Automatic Tracking
• AI Agent Quota Monitor: Refresh Usage
• AI Agent Quota Monitor: View Details
• AI Agent Quota Monitor: Reset Local State

Settings

Run and debug

Requirements: Node.js 20+ and VS Code 1.90+.

npm install
npm test
npm run check-types
npm run lint

Open this folder in VS Code and press F5 to launch an Extension Development Host. Logs appear in Output → AI Agent Quota Monitor.

To run the VS Code Extension Host suite:

npm run test:extension

To create a VSIX (the first run may download @vscode/vsce):

npm run package

Troubleshooting

• Codex: Not connected: Run Connect Codex. If Codex is not found, configure its absolute executable path. Check the output log for App Server startup or authentication errors.
• Claude: Not connected: Enable the bridge, start Claude Code, and send one request. Pro/Max rate-limit fields arrive after the first Claude API response.
• Claude values are stale: Claude Code has not emitted a new status-line payload. The displayed reset countdown is based on the last official timestamp.
• Existing Claude status line changed: Disable will intentionally leave it untouched. Re-enable to adopt the current command as the new chained predecessor, or restore it manually.
• Too many alerts: Choose Mute Alerts in a usage alert, disable aiTokenTracker.enableModalAlerts, or reduce aiTokenTracker.alertMilestones.

Clean disable / uninstall

Before uninstalling, run Disable Claude Automatic Tracking so the prior Claude status-line setting is restored. Disabling the VS Code setting alone pauses ingestion but intentionally does not edit Claude configuration. Bridge files under VS Code global storage contain no credentials and may be deleted after clean disable.

Implementation references: Codex App Server and Claude Code status-line data.