🔋 Claude & Codex Usage Battery

A macOS menu bar widget that shows your remaining Claude Code and Codex usage limits as battery icons — so you never have to open /usage again.

C = Claude · X = Codex. Each battery shows the remaining % of a limit window — full & green means plenty left, red means almost out. Click for a detailed breakdown with reset times.

Built as a single SwiftBar plugin — one self-contained script, no third-party libraries. The battery icons are rendered as PNGs from scratch in pure JavaScript (node:zlib only), so there's no image library and no npm install. Network calls: two official usage endpoints — Anthropic's and OpenAI's — each fetched with your own local Claude Code / Codex login (the same data /usage and Codex's /status show — see Privacy), plus an optional once-a-day update check (see Updating). (ccusage is an optional extra for the cost breakdown.)

What it shows

Click the widget for a dropdown with, per limit:

Claude Code
  5h remaining   ▕██████████████░░░░░░▏ 70%  (used 30%)  · resets 3h 18m
  weekly         ▕██████▋░░░░░░░░░░░░░▏ 33%  (used 67%)  · resets 3d 21h
  Fable          ▕████░░░░░░░░░░░░░░░░▏ 26%  (used 74%)  · resets 3d 21h
  today by model ▕████████████▏ Fable $75 · Opus $46 · Sonnet $5 …

Codex · prolite
  5h remaining   ▕████████████████████▏ 100% (used 0%)
  weekly         ▕████████████████▋░░░▏ 83%  (used 17%)

Colors follow a traffic-light scale: green ≥ 50 % left, amber < 50 %, red < 20 %.

Requirements

Note: This widget shows your own account's limits — via your local Claude Code login and your local Codex session logs. If you don't use Claude Code (or Codex), there simply won't be any data to display.

Install

git clone https://github.com/dennykim123/claude-codex-battery.git
cd claude-codex-battery
./install.sh

install.sh will:

1. Verify bun and SwiftBar are present (and tell you how to install them if not)
2. Copy the plugin into ~/.swiftbar-plugins/, rewriting the shebang to your machine's bun path (SwiftBar runs plugins with a minimal PATH, so an absolute shebang is required)
3. Point SwiftBar at the plugin folder and launch it
4. Register SwiftBar as a login item, so the battery comes back automatically after a reboot

No npm install, no bundled libraries — the plugin is a single self-contained script.

The battery appears in your menu bar within a few seconds. It refreshes every 2 minutes (the .2m. in the filename).

Manual install

If you prefer not to run the script:

mkdir -p ~/.swiftbar-plugins
# rewrite shebang to your bun path, then copy:
sed "1s|.*|#!$(command -v bun)|" claude-codex-usage.2m.js > ~/.swiftbar-plugins/claude-codex-usage.2m.js
chmod +x ~/.swiftbar-plugins/claude-codex-usage.2m.js
defaults write com.ameba.SwiftBar PluginDirectory -string ~/.swiftbar-plugins
open -a SwiftBar

Updating

The widget checks GitHub for a newer version at most once a day — a tiny background request for the VERSION file. When a new version is out, a green 🆕 update row appears in the dropdown; click it to replace the plugin in place and refresh (your previous copy is kept as .bak). There's also an always-visible ⬆️ update now row that replaces the plugin with the latest main on demand — no waiting for the daily check.

Prefer to do it yourself? From your clone: git pull && ./install.sh.

To turn the check off entirely, comment out the getUpdateInfo() call near the bottom of the script — then the only network call left is the Anthropic usage query.

Privacy & security

• Claude limits come straight from Anthropic. The widget reads your Claude Code OAuth token from the macOS Keychain (item Claude Code-credentials) and calls api.anthropic.com/api/oauth/usage — the same endpoint /usage uses. The token is sent only to api.anthropic.com, passed via stdin (never visible in ps), and never written to disk or logs. macOS may show a one-time Keychain permission prompt — click Always Allow. (Clicking Deny makes macOS re-prompt on every refresh — if you'd rather the widget never touch the Keychain, run touch ~/.claude/swiftbar/.no-live instead; it then reads local cache files only, like v1.1.)
• Codex limits come straight from OpenAI. Likewise, the widget reads your Codex OAuth token from ~/.codex/auth.json and calls chatgpt.com/backend-api/wham/usage — the same account-level endpoint Codex CLI polls itself. The token is sent only to chatgpt.com, via stdin (never visible in ps), and never written to disk or logs. (touch ~/.claude/swiftbar/.no-live disables both live queries; it then reads local files only.)
• No API keys touched. Only the OAuth login tokens above are read — never any OPENAI_API_KEY / ANTHROPIC_API_KEY.
• No usage data leaves your machine. Nothing is uploaded anywhere; the only outbound calls are the two usage queries above (to Anthropic and OpenAI) and the optional daily update check (Updating).
• No conversation content. From the Codex session-log fallback it parses only the rate_limits object (numbers), never the messages.
• Auditable in one sitting. The whole widget is a single dependency-free script — grep for curl/fetch and you've seen every network call it can make.

How accurate / in-sync is it?

Claude — live. Every refresh queries Anthropic's usage API directly with your local Claude Code login — the same server-side data /usage shows, so the numbers match it by construction. Because the limits are account-level, usage from every surface and device (terminal, desktop app, web, another machine) is already included. If the query fails (offline, logged out), the widget falls back to its last successful response and labels the reading with its age in amber.

Codex — live too. The widget queries the same account-level usage endpoint Codex CLI polls internally (backend-api/wham/usage), using your local Codex login token. It's a read-only call that costs no tokens, and because it's account-level, all your machines see the same numbers — so two Macs stay in sync. If the query fails (offline, logged out), it falls back to the newest local session log (labeled "measured N ago", warns past 3h) and then to its last live response.

TL;DR — Both Claude and Codex are live and account-level, so every device shows the same numbers. When a live query fails, each falls back to a clearly-labeled cached/snapshot reading.

How it works

The whole thing is one .js file run by bun on a timer.

• Battery icons are drawn pixel-by-pixel into an RGBA buffer and encoded to PNG using only node:zlib (hand-rolled CRC32 + IHDR/IDAT/IEND chunks). A 5×7 bitmap font renders the numbers and the C/X group labels. SwiftBar displays the PNG at pixels ÷ 2 pt.
• Claude limits are fetched from Anthropic's OAuth usage endpoint using the Claude Code login token in your Keychain, with the last good response cached at ~/.claude/swiftbar/.claude-usage.json as an offline fallback. The Fable cap is the weekly_scoped entry.
• Codex limits are fetched live from backend-api/wham/usage with the token in ~/.codex/auth.json, normalized to the same shape as the session-log format, and cached at ~/.claude/swiftbar/.codex-usage.json as an offline fallback (with the newest session log as a second fallback). The premium plan reports a credits object instead of percentages when exhausted; the widget handles both shapes.

Codex has one quirk

Codex only writes limit data to session logs while you use it, and doesn't record a reset time when exhausted. So if you haven't run Codex in a while, the value can be stale. The widget:

• flags values older than 3 hours in the dropdown, and
• optionally