For agents

Let your agent check before the big job.

Fuel Gauge includes a fuelgauge command. It prints the forecast for every limit and exits with code 2 when one will run out before it resets, so a coding agent can ask you before it burns through what's left.

The short answer

Run fuelgauge status. It exits 0 when every limit will last until it resets, and 2 when one won't (or already ran out). Add one line to CLAUDE.md or AGENTS.md and your agent checks before long tasks. Homebrew puts the command on your PATH; otherwise use Settings › General › Install.

Commands

fuelgauge status              # every limit, in plain words; exits 2 if one will run out before it resets
fuelgauge status --json       # the same, for scripts and agents
fuelgauge history --days 2    # the readings behind the forecasts
fuelgauge install-statusline  # make Fuel Gauge Claude Code's status line (keeps yours, backs up settings.json)
fuelgauge uninstall-statusline

What status prints

Claude Code · 5-hour: Runs out around 11:50a, 1h 30m early
  55% used · resets 1:20p (in 3h 6m)
  Using 28% an hour. You can use up to 15% an hour and still make it.
Claude Code · Weekly: Makes it to reset, about 86% by then
  41% used · resets Thu 9a (in 2d 22h)

The JSON

fuelgauge status --json prints one object per limit, with stable snake_case keys:

[
  {
    "tool": "claude",
    "window": "5-hour",
    "used_percent": 55,
    "resets_at": "2026-10-20T20:20:00Z",
    "verdict": "runs_out",
    "runs_out_at": "2026-10-20T18:50:00Z",
    "rate_per_hour": 28,
    "budget_per_hour": 15,
    "summary": "Runs out around 11:50a, 1h 30m early"
  }
]

verdict is one of makes_it, runs_out, out, learning, or reset. Exit code 2 means at least one limit is runs_out or out.

Add it to 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.

Then every agent session checks before the expensive stuff, and tells you which limit runs out and when instead of hitting the wall halfway through.

Install it with your 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`.

Questions

What does exit code 2 mean?

At least one tracked limit is forecast to run out before it resets, or has already run out.

Does the command need the app running?

The app collects Codex and Grok Bot readings in the background; Claude Code readings arrive through the status line. Keep the app running for current Codex numbers.

Is the JSON stable?

Yes. Keys are snake_case and new fields are only ever added.

Know if you'll make it to reset.

Free. No account, no subscription.

Download for Mac View source code

brew install --cask coreyhaines31/tap/fuelgauge

Or ask your 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`.

macOS 14 Sonoma or later · Apple Silicon and Intel