Fuel Gauge puts four Claude Code readouts in your VS Code status bar: how full the context window is, how long your prompt cache has left, which model and effort level the session is running, and how close you are to your usage limits on Anthropic subscription plans.
Fuel Gauge never logs into your Claude account. It has no account of its own, no API key and no telemetry, and it makes no network calls of any kind. Every number it shows comes from files Claude Code already writes on your own disk.
The complete list of every file it reads and writes — there are five, all under ~/.claude or VS Code's own storage — is in Privacy further down, and in SECURITY.md.
Anthropic keeps the front of your conversation warm in a prompt cache, for five minutes or an hour depending on your plan. While it is warm, your next message reuses it. Let it go cold and the whole conversation is read again from the start: the next turn is slower, and on API billing it costs more.
Fuel Gauge shows the time you have left as its own status bar item, with its own colour, so cache urgency reads independently of how full your context is. None of the other Claude Code extensions I checked in August 2026 shows this. Here a comfortable 10% context sits in green next to an expired cache in red — and the amber dot on the right is the usage alert, lit because a usage limit crossed 70%.
- Counting down —
M:SS, inherits the context colour while there is comfortable time left - Warming (<60s) — yellow
- Expiring (<15s) — red
- Expired —
expiredlabel in red with a circle-slash icon - Hidden — when there is no cache state yet (fresh session, just after
/compact)
How exact it is. The cache lifetime is read, not guessed. Claude Code records on every turn which cache it asked for, the five-minute one or the one-hour one, and Fuel Gauge reads the most recent of those entries from the end of the session transcript. That reading is exact, and it corrects itself on the next update. The answer is saved to ~/.claude/fuel-gauge/account_ttl.json, so a new session's countdown is right from its first second.
The countdown itself starts again from the full lifetime on every status line update, so it tracks the last activity Claude Code reported. If the record cannot be read — an older Claude Code that does not say where the transcript is, or a file that will not open — Fuel Gauge falls back to the one thing the token counts can prove on their own: a cache that survived more than five minutes is not a five-minute cache. fuel-gauge.cacheTTL overrides all of it, if you would rather fix the value yourself.
Fuel Gauge shows up to four items, right-aligned, and one shared hover tooltip that breaks everything down.
How full the window is, live from 0% and colour-coded green → yellow → red. It covers claude sessions in the integrated terminal, which Claude Code's own indicator does not.
- Active — coloured percentage, using your thresholds
- Stale — percentage with a circle-slash icon, no colour (no update for over an hour, a genuinely abandoned session)
- Reading paused —
~42%, no colour: right after/compactClaude Code reports an empty context window until your next turn, so the gauge holds the last number it had and marks it with a tilde rather than dropping to a green 0% - No session — the gauge is hidden. It appears when a Claude Code session starts in the folder this window has open
The percentage is exactly the one Claude Code reports. Run /context in a session, or read Claude Code's own status line, and you will see the same figure. It will not match the small pie in the VS Code prompt box, or the "Context low" message in the terminal, because those two measure how much room is left before Claude Code compacts your conversation automatically, and they measure it against a smaller window. They answer a different question, so their numbers differ. See Known issues.
A compact item like opus·x-high, coloured by effort level, gold when you are running max. Hover for the full model name and the effort spelled out. Seeing opus·max on a medium-sized task is what makes you dial it down, and effort is a large lever on tokens burned. Hide the item with fuel-gauge.effortStyle: off. The effort part only appears when the current model reports an effort level.
It also shows you when a session is no longer running the model you picked. Anthropic's Fable tier ships with additional safety measures for dual-use capabilities: when Fable's classifiers detect a request in certain areas — cybersecurity, for one — the response is handled by Opus instead, by Anthropic's own account. Claude Code does announce the switch, but the notice is easy to miss in the stream of terminal text — fable·x-high becoming opus·x-high in the status bar stays put until you see it.
Your session (5-hour) and weekly usage live in the hover tooltip, each with its reset time. To keep the bar quiet, that is the only place the numbers appear, until a limit gets high:
- Running hot — when your 5-hour or weekly usage crosses 70%, a coloured dot appears in the bar (yellow ≥70%, red ≥90%). Hover it for the exact percentages and reset times.
- Hidden — below 70%, and whenever Claude Code sends no limit data (API-key sessions, or before the session's first response). Hidden means hidden: no misleading 0%.
Turn the whole usage display off with fuel-gauge.showUsage: false.
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-gaugeFor 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 else automatically.
Claude Code has a statusline feature that exposes session data as JSON. Fuel Gauge uses it in two parts:
- Bridge script — installed automatically on first activation. Claude Code pipes session data to it, and it writes one small JSON file per session to
~/.claude/fuel-gauge/. - Extension — polls that directory every 15 seconds, finds the session matching your current workspace, and shows the numbers in the status bar.
Everything — context, cache, model, effort, usage limits — rides that same local feed. No network calls, no API keys, no accounts.
Works for both the built-in VS Code extension's sessions and claude sessions in the integrated terminal.
Claude Code allows one status line command. Fuel Gauge needs it, because the 5-hour and weekly usage percentages exist nowhere else on your machine — they are not in the session transcripts and no hook receives them.
So if you already run your own status line (ccstatusline, a powerline script, anything), Fuel Gauge asks before taking the slot, saves what was there, and can put it back:
- Fuel Gauge: Restore Previous Status Line — puts your command back and stops Fuel Gauge managing the slot.
- Fuel Gauge: Connect Status Line — asks again if you declined.
- Claude Code Fuel Gauge: Show Diagnostics — read-only report if the gauge is dark.
fuel-gauge.manageStatusLine— set tofalseto keep Fuel Gauge away from your settings entirely.
The two cannot run at the same time. That is a Claude Code limitation, not a choice I made.
- VS Code 1.93+ (or a compatible fork)
- Claude Code CLI — works with any model and with both the 200k and 1M-token context windows
bashand Python 3 — the bridge script is a shell script that usespython3to read Claude Code's JSON. On macOS,python3comes with the Xcode Command Line Tools. Most developers already have them; if you do not, the first run pops Apple's "Install command line developer tools?" dialog. Install them once withxcode-select --installand the gauge works from then on.- Built and tested on macOS. Linux should work — the bridge needs nothing beyond
bashandpython3— but I have not run it there. Windows is untested; the bridge is a bash script, so at minimum it needs abashon the path. - Usage limits display: a Claude subscription plan (Pro/Max). API-key sessions don't have these limits, so the display stays hidden.
- Usage limits on a Team plan: Claude Code does not send the limit numbers to the status line for Team plan sessions (claude-code#84995), so the usage alert dot and the 5-hour and weekly lines in the hover stay empty there. Everything else works normally.
| Setting | Default | Description |
|---|---|---|
fuel-gauge.pollInterval |
15 | How often to check for updates (seconds) |
fuel-gauge.warningThreshold |
60 | Context % at which the indicator turns yellow |
fuel-gauge.dangerThreshold |
80 | Context % at which the indicator turns red |
fuel-gauge.systemOverhead |
0 | Deprecated, and safe to delete from your settings. A number of tokens to subtract from the context window before working out the percentage. Used only if Claude Code sends no percentage of its own |
fuel-gauge.cacheTTL |
null (auto) |
How long the prompt cache lives, in seconds. Leave it empty and Fuel Gauge reads the answer from Claude Code's own record. Set 300 (5 minutes) or 3600 (1 hour) only to override that |
fuel-gauge.cacheWarningSeconds |
null (off) |
Play 3 short beeps when the cache countdown drops below this many seconds. macOS only. Example: 180 for a 3-minute warning |
fuel-gauge.effortStyle |
text |
Model·effort item: text to show it, off to hide it |
fuel-gauge.showUsage |
true |
Show session/weekly usage in the hover, with the alert dot when a limit is high |
fuel-gauge.manageStatusLine |
true |
Let Fuel Gauge use Claude Code's status line slot. Set to false to keep it out of ~/.claude/settings.json entirely — the gauge then shows nothing |
To hide one of the four items without hiding the rest, right-click the status bar itself: VS Code lists them as Fuel Gauge: context, cache countdown, model and effort and usage alert, and remembers what you switch off. No setting needed.
The percentage will not match VS Code's pie or the "Context low" message. Those measure how close you are to an automatic compact, against a smaller window. Fuel Gauge matches /context and Claude Code's own status line. Neither reading is wrong; they count different things.
No per-model weekly bar. /usage shows Max users a per-model figure that Claude Code does not put in the status line data, and the only other way to it is a web request with your login credentials — which Fuel Gauge will not make. If Anthropic adds it to the status line, it will show up here.
Usage can be missing. The limit numbers arrive only on subscription plans, and only after the session's first response. Fuel Gauge hides the display rather than show a false 0%.
Empty in an untrusted folder. Claude Code runs the status line command only after you accept its workspace-trust prompt. Trust the folder and restart the session.
Stale numbers on macOS (rare). An upstream Claude Code bug (#32660) can silently stop the status line firing. Restarting the Claude Code session fixes it.
Workspace matching. The gauge follows the session started in the folder your window has open. A session launched from a different directory is not shown — by design, since the status bar belongs to the workspace.
Icons in forks. Editors without the newer codicons (Antigravity, for one) show only the gauge icon, not the Claude icon next to it. Everything works the same.
If something is broken, open an issue and pick the bug report template. It asks you to paste the output of the Claude Code Fuel Gauge: Show Diagnostics command, which lists your settings file, the bridge script and the session files Fuel Gauge can see — that report answers most of the questions I would otherwise have to ask you, so please include it. Questions about how any of this works belong in Discussions under Q&A, and things you would like Fuel Gauge to do belong in Discussions under Ideas. If the extension is working for you, please leave a review on the Marketplace — reviews are how other people find it.
If you would rather not use GitHub — or you want to talk about something that does not belong on a public tracker — email info@makingaipractical.com. And if you want to send a patch, CONTRIBUTING.md says how to run everything locally.
No API calls, no telemetry, no runtime dependencies, no account. Everything runs locally on Claude Code's own statusline data, including the usage numbers. This is the complete list of what Fuel Gauge reads and writes:
| File or folder | What Fuel Gauge does with it |
|---|---|
~/.claude/settings.json |
Reads it. Writes one key, statusLine.command, and only after you agree to it. Every other setting is left as it was. |
~/.claude/scripts/context-bridge.sh |
Writes the bridge script that Claude Code pipes its status line data to. If a different script is already there, it is copied aside first. |
~/.claude/fuel-gauge/ |
Writes one small JSON file per Claude Code session, and reads them back to draw the status bar. |
Claude Code's session transcript, under ~/.claude/projects/ |
Reads the end of the current session's file, to find out whether your plan's prompt cache lasts five minutes or an hour. Two token counters are used. Nothing is written there, and no message text is read. |
| VS Code global storage | Writes a copy of your previous status line command, so that Restore Previous Status Line always has something to give back. |
Nothing else is read, nothing else is written, and nothing leaves the machine. The same list is in SECURITY.md, together with how to report a vulnerability privately.
This is a community tool. Not made by, endorsed by, or affiliated with Anthropic.
v0.9.1 — The cache countdown now reads your plan's cache lifetime from Claude Code's own record instead of inferring it from token behaviour, which ends the false expired some sessions saw. After /compact, the gauge holds its last reading as ~42% instead of dropping to a green 0%. Each of the four items can be hidden on its own from the status bar's right-click menu. The cache hover names the clock time the cache expires. And the gauge hides itself in windows with no matching session.
v0.9.0 — The context percentage is now exactly the one Claude Code reports — the same number /context gives you. Earlier versions applied a correction that read a few points too high, so your percentage drops a little on upgrade; nothing about your session changed. Fuel Gauge also now asks before taking the status line slot, saves what was there, and adds Restore Previous Status Line, Show Diagnostics and the fuel-gauge.manageStatusLine setting.
v0.8.x — The model·effort indicator and the usage limits display: session and weekly numbers in the hover, and the alert dot when a limit runs hot.
v0.6.x — The cache countdown: the M:SS item with its urgency colours, the optional audio warning, and the detected lifetime remembered across sessions.
v0.5.0 — Renamed from BrainDrain CC to Claude Code Fuel Gauge.
The full change-by-change record is in CHANGELOG.md. Previously released as BrainDrain CC (v0.1.0–v0.4.4).
This page was written by Claude (Fable) and me. Fuel Gauge itself was developed with Claude Code.