# Fuel Gauge

> Fuel Gauge is a free, source-available macOS menu bar app (macOS 14 Sonoma or later) that forecasts whether your Claude Code, Codex, and Grok Bot plan limits will last until they reset. It reads only what those tools already save on your Mac, and sends nothing anywhere.

- Install: `brew install --cask coreyhaines31/tap/fuelgauge`, or download https://github.com/coreyhaines31/fuelgauge/releases/latest/download/FuelGauge.dmg
- Source: https://github.com/coreyhaines31/fuelgauge (FSL-1.1-MIT)
- Limits tracked: Claude Code 5-hour and weekly, Codex weekly, Grok Bot weekly, and Cursor monthly (opt-in: asks cursor.com with the Cursor app's sign-in). Choose which in Settings › Tools.
- How it forecasts: readings come from Claude Code's status line (every time Claude Code replies), Codex's session logs (`~/.codex/sessions`), and Grok Bot's local usage cache. Pace is the climb over the last hour for 5-hour windows and the last day for weekly ones. It needs about 10 minutes of readings first, and shows a range, not an exact minute. It's an estimate from recent pace, not a promise.
- Command line: `fuelgauge status` prints the verdict for each limit and exits with code 2 when a limit is forecast to run out before it resets. `fuelgauge status --json` has the details. `fuelgauge history` shows the readings. `fuelgauge install-statusline` adds the forecast under Claude Code's prompt (keeping any existing status line and backing up settings.json), and `fuelgauge uninstall-statusline` removes it.
- Install prompt for a coding agent: "Install Fuel Gauge on my Mac: run `brew install --cask coreyhaines31/tap/fuelgauge`, open Fuel Gauge, then run `fuelgauge install-statusline` and `fuelgauge status`."
- Line for CLAUDE.md or AGENTS.md: "Before starting a long or expensive task, run `fuelgauge status`. If it exits with code 2, a Claude Code, Codex, or Grok Bot limit is forecast to run out before it resets: tell me which one and when, and ask before starting, or switch to a cheaper model. `fuelgauge status --json` has the details."
- Uninstall: run `fuelgauge uninstall-statusline` first, then `brew uninstall --cask fuelgauge`.
- Privacy: no browser cookies, no Full Disk Access, no keychain, no sign-in, zero telemetry. The only network request is the update check. Details: https://fuelgauge.app/privacy

## Compared with other apps

- [Fuel Gauge vs CodexBar](https://fuelgauge.app/codexbar-alternative): Pick CodexBar if you use many AI providers and want them all in one menu. Pick Fuel Gauge if you live in Claude Code, Codex, or Grok Bot and want the verdict first, a forecast under your Claude Code prompt, and an exit code your agents can check. Fuel Gauge reads only local files.