Claude Code Fuel Gauge

Claude Code Fuel Gauge shows you how much context runway you have in your current session, even when you are running multiple sessions at a time.

In Claude Code's VS Code extension, you don't see context usage until it warns you. Fuel Gauge puts a live percentage in your status bar, color-coded green → yellow → red, so you see it coming.

Works in VS Code, Antigravity, and other VS Code forks.

Why Fuel Gauge

• You see it coming. No more surprise "context low" warnings. You see the percentage climbing and can plan your exit before quality drops.
• Stay in the flow. No command to type, no window to open. Glance at the status bar, keep working.
• Session planning. At 60%, you know you can fit one more big task. At 80%, you know to wrap up. Context becomes a resource you manage, not a cliff you fall off.
• You stop needing the /context command in Claude Code.
• You can disable /autocompact and manage your own context because you can see it.

Why not just use /context?

Fuel Gauge calculates usage from both input and output tokens, and compensates for system token overhead that Claude Code doesn't expose in its statusline data. Claude Code's /context command and its statusline used_percentage only count input tokens and exclude system overhead, so they can report free space when you're effectively at the limit. With the right systemOverhead setting, Fuel Gauge's percentage closely tracks the "Context low" warning that Claude Code shows in the terminal.

Display states

• Active — colored percentage (green/yellow/red based on thresholds)
• Stale — percentage with a circle-slash icon, no color (no update for >5 minutes)
• No session — 0%, no color

Install

Search for Claude Code Fuel Gauge in the VS Code Extensions panel, or install from the command line:

code --install-extension makingaipractical.claude-code-fuel-gauge

For VS Code forks like Antigravity, download the .vsix from the Releases page and install via the extensions panel (three dots > "Install from VSIX").

Restart any running Claude Code sessions after installing. The extension sets up everything automatically.

How it works

Claude Code has a statusline feature that exposes context window data as JSON. Fuel Gauge uses this in two parts:

1. Bridge script — automatically installed on first activation. Claude Code pipes context data to this script, which writes a JSON file per session to ~/.claude/fuel-gauge/.

2. Extension — polls that directory every 15 seconds, finds the session matching your current workspace, and displays the percentage in the status bar.

Each VS Code window shows the context for its own workspace. Multiple concurrent Claude Code sessions are supported — one per project directory.

Requirements

• VS Code 1.93+ (or compatible fork)
• Claude Code CLI (works with both 200k and 1M token context windows)
• Python 3 (used by the bridge script to parse JSON)

Settings

Known issues

Accuracy depends on system overhead. Claude Code uses hidden tokens (system prompt, tool definitions, MCP configs, CLAUDE.md) that aren't reported in statusline data. Fuel Gauge compensates with a configurable systemOverhead setting (default 18,000 tokens). If your percentage consistently underreports compared to Claude's "Context low" warning, increase this value. In practice, the default overhead is quite accurate.

Status bar stops updating on macOS. Claude Code has an upstream bug (#32660) where the statusline command can silently stop firing on macOS. When this happens (sometimes after "/resume", but not always), Fuel Gauge shows a stale percentage or stays at 0%. Restarting the Claude Code session usually fixes it. No workaround exists at this time.

Workspace matching. The status bar shows context for the Claude Code session whose project directory matches the VS Code workspace folder. If you run Claude Code from a different directory than the one open in VS Code, Fuel Gauge won't pick it up. This is by design — the status bar belongs to the workspace.

Icon differences across editors. In VS Code, the status bar shows a Claude icon alongside a dashboard gauge. In forks like Antigravity that don't include newer codicons, only the gauge appears. Functionality is identical.

Privacy

No API calls, no telemetry, no runtime dependencies. Everything runs locally using Claude Code's own statusline data.

Not affiliated with Anthropic

This is a community tool. Not made by, endorsed by, or affiliated with Anthropic.

Version History

v0.5.0 — Renamed from BrainDrain CC to Claude Code Fuel Gauge. New dashboard gauge icon, new screenshots, improved Marketplace discoverability.

Previously released as BrainDrain CC (v0.1.0–v0.4.4).