AI Usage

Shows your current Codex and Claude usage limits inside VS Code: the 5-hour window, the weekly window, when each resets, when the numbers were last refreshed, and whether they are stale.

AI USAGE

CODEX
5h       ███████░░░░░░░  34%
Weekly   ████████████░░░  62%
5h reset       14:20
Weekly reset   Friday 11:47

CLAUDE
5h       ███░░░░░░░░░░░  19%
Weekly   ████████░░░░░░░  43%
5h reset       16:00
Weekly reset   Monday 09:00

Updated 13:12                  ↻

The extension only runs two local command-line tools and renders their output. It does not read, store or send API keys, has no telemetry, and makes no network calls of its own.

Supported environments

It is one package with one extension ID (left-code.vscode-ai-usage). It runs on Windows and Linux (and works in WSL/Remote windows when the tools are installed where the extension host runs). Requires VS Code 1.90 or newer.

Requirements

The extension does not talk to OpenAI or Anthropic itself. It needs these two tools, already installed and signed in:

Both are Python tools (Python 3.12+), for example:

uv tool install codex-cli-usage
uv tool install ccusage

They use your existing Codex CLI / Claude Code login. You never give this extension a key.

Not the npm ccusage. There is an unrelated npm package with the same name that analyses token costs and has no json subcommand. Make sure ccusage --help lists status, json, refresh, daemon, statusline, install. If it does not, set aiUsage.claude.command to the right executable.

What the tools return (verified against the installed versions)

codex-cli-usage json — a live request, exits 1 on failure:

{ "schema_version": 2, "plan": "plus", "source": "api", "updated_at": "…",
  "primary":   { "pct": 75, "resets_at": "…", "window_secs": 18000 },
  "secondary": { "pct": 19, "resets_at": "…", "window_secs": 604800 },
  "5h": { … }, "7d": { … } }

Windows are classified by window_secs (≈5 h → 5-hour, ≈7 d → weekly), because some plans report the weekly window as primary.

ccusage json:

{ "updated_at": "…", "session": { "pct": 0, "resets_at": "…" }, "7d": { "pct": 18, "resets_at": "…" }, "extra_usage": { … } }

session is the 5-hour window and 7d the weekly window. Important: when its live request fails, ccusage json silently prints its last cached file, still with exit code 0. The extension therefore checks updated_at and treats anything older than 2 minutes as a failed refresh, so cached values are never shown as current. pct is always percent used.

Installation

From a VSIX

npm install
npm run package          # creates vscode-ai-usage-<version>.vsix
code --install-extension vscode-ai-usage-0.1.2.vsix

Development

npm install
npm run compile          # or: npm run watch

Open the folder in VS Code and press F5 (Extension Development Host).

Using it

• Open the AI Usage icon in the Secondary Sidebar (or run View: Focus on AI Usage View).
• Refresh with the ↻ button, the view-title button, or AI Usage: Refresh.
• Colours come from the active theme (light, dark and high contrast). Bars turn warning/error coloured from 70 % / 90 %.
• All times are shown in 24-hour format (14:20, Friday 11:47), regardless of your language or OS clock setting.

Status bar

Off by default. Set aiUsage.statusBar.enabled to true to show Codex 34/62% Claude 19/43% in the status bar. The numbers are percent used, 5-hour / weekly. Hovering shows the full detail (bars, reset times, stale notes); clicking opens the details drawer. A provider that is stale gets a ⚠ and the whole item turns warning-coloured; a provider that has no data shows ⚠ alone. The setting applies immediately.

The drawer is a list you can also open any time from the Command Palette (AI Usage: Show Details):

CODEX
5h      ▰▰▰▰▰▰▰▱▱▱   75%   5h reset 16:16
Weekly  ▰▰▱▱▱▱▱▱▱▱   19%   Weekly reset Monday 11:47
CLAUDE
…
Updated 14:18
Refresh now · Show text summary · Show log

Commands

There are deliberately no "Open Codex/Claude Usage" commands: neither the Codex nor the Claude Code extension exposes a command that opens a usage screen, and inventing one would be guesswork.

Refresh behaviour

• Refreshes on activation, every aiUsage.refreshIntervalMinutes (default 2, minimum 0.5), when the view becomes visible, and on demand.
• Never overlaps: a manual refresh during a running one joins it. The next automatic refresh is scheduled only after the previous one finishes.
• Each provider is independent: one failing never blanks or delays the other.
• A failed refresh never overwrites the last good values. They stay visible, marked STALE, with "⚠ Last refresh failed" and "Last successful update: 13:08". Data that simply stops being refreshed is flagged too, after max(5 min, 2.5 × interval).
• No values are cached on disk. Every VS Code window / extension host refreshes independently, so nothing can stay "stuck" from an old cache file.

Agents window

The VS Code Agents window (preview) only runs extensions that are explicitly opted in. To use this extension there:

1. Install it in your default VS Code profile (the Agents window needs it there).

2. Opt in, either by running AI Usage: Enable in Agents Window in a normal window, or by adding this to your user settings.json:

   "extensions.supportAgentsWindow": {
       "left-code.vscode-ai-usage": true
   }
   

3. Reopen the Agents window.

This is the only supported mechanism: the alternative manifest capability (capabilities.agentsWindow) needs the proposed API agentsWindowActivation, which this extension deliberately does not use. Without the opt-in, the Agents window does not load the extension at all.

Limitation (VS Code 1.139). The Agents window has its own fixed layout. It only shows view containers that VS Code itself registers for it (Changes, Files, Chat Debug, plus the shared Output, Problems and Terminal panels); view containers contributed by extensions are not shown there, and there is no manifest setting to change that. So in the Agents window the extension activates and refreshes normally, but the sidebar view is not available. Instead, open AI Usage: Show Summary (or pick AI Usage Summary in the Output panel) for a plain-text version with the same stale/error states:

CODEX
  5h        34%   5h reset: 14:20
  Weekly    62%   Weekly reset: Friday 11:47

Where to look in the Agents window. Open the bottom Output panel (Ctrl+Shift+U, or the Command Palette entry above) and choose AI Usage Summary in the dropdown at its top right. It is rewritten on every refresh. Verified in VS Code 1.139.1: the extension activates there and the channel shows live data. It will not appear under Sessions, Automations, Chats or Customizations (Plugins, MCP Servers, Skills, Hooks, …): those are built-in pages that extensions cannot add to. The Agents window also has no status bar, so aiUsage.statusBar.enabled has no effect there.

If a later VS Code release lets extension views appear in the Agents window, the same package will pick that up without changes.

Configuration

Executables are found only via the configured absolute path or PATH; no other directories are searched. They are started directly (never through a shell). On Windows only real executables (.exe/.com) are supported; .cmd/.bat wrappers cannot be started without a shell.

Troubleshooting

"Usage unavailable — codex-cli-usage was not found" / "ccusage was not found on PATH" The tool is not installed, or not on the PATH seen by VS Code. Check with codex-cli-usage json / ccusage json in a terminal. VS Code only picks up PATH changes after it is fully restarted. Alternatively set aiUsage.codex.command / aiUsage.claude.command to an absolute path.

Codex usage unavailable, "Authentication refresh failed. Run codex login again." Sign in to the Codex CLI again (codex login), then refresh.

Claude usage unavailable, "open Claude Code to log in/refresh it" The Claude Code OAuth session expired. Start claude once and sign in. If it says usage is unavailable because "OAuth is not allowed for this organization" or no active subscription, the account does not expose usage through this interface.

"ccusage failed: …" with a usage message You probably have the npm ccusage. See the note under Requirements.

"returned cached data from N min ago (live fetch failed)" The tool could not reach the service and fell back to its cache; the extension refuses to show that as current. Check your connection or login. The last good values (if any) stay visible, marked STALE.

A provider shows STALE Its last refresh failed or hasn't succeeded recently. The message under the bars says why and when the last success was. Use AI Usage: Show Log for details.

Nothing at all in the Agents window See Agents window: the extension must be opted in and the window reopened, and the sidebar view is not shown there. Open the Output panel (Ctrl+Shift+U) and select AI Usage Summary. If that entry is missing, the extension did not load: check that it is installed in the default profile and that the setting key is exactly left-code.vscode-ai-usage.

Two windows open Each window refreshes on its own, so the tools run once per window per interval. Increase aiUsage.refreshIntervalMinutes if that matters.

Development

npm run compile            # TypeScript → out/
npm run lint               # ESLint
npm run format:check       # Prettier
npm test                   # unit tests (Node test runner, fixtures only — no real accounts needed)
npm run test:integration   # launches a real VS Code, activates the extension, runs the real tools
npm run package            # VSIX

Layout:

src/extension.ts                       activation, wiring, Agents-window opt-in command
src/models/usage.ts                    normalized data model
src/providers/                         UsageProvider interface, Codex + Claude providers/parsers
src/services/commandRunner.ts          direct process execution: timeout, cancel, tree-kill, output cap
src/services/executableResolver.ts     configured path → PATH lookup
src/services/usageService.ts           refresh state, locking, last-good data, stale classification
src/services/refreshScheduler.ts       interval / visibility-triggered refresh
src/views/                             view model, WebviewView provider, text summary
media/                                 webview script + theme-variable CSS (no framework)
src/test/                              unit tests + fixtures; src/test/integration/ runs inside VS Code

test:integration uses your installed VS Code (or VSCODE_EXECUTABLE) with a throw-away profile; it needs codex-cli-usage and ccusage installed and signed in.

Privacy

No API keys are read or stored, no credentials or session data are logged (tool error text is reduced to one redacted line), no telemetry is sent, and the extension makes no network requests itself — the two local tools you install make the requests using your existing logins.

License

MIT