Battery

A native macOS menu bar app that monitors your Claude Code API usage in real time. Session gauges, weekly tracking, burn rate projections, and usage streaks - all living in your menu bar.

$ brew tap allthingsclaude/battery

$ brew install --cask claude-battery

Star us on GitHub↗

38% · 1h 59m

Battery

Session (5-hour)

38%used

1h 59m remaining

Weekly (7-day)26% used

Resets on Sunday, Feb 15 at 3:00 PM

Extra Usage56%

$56.46 / $100.00$43.54 remaining

Projections

Increasing

Limit in 3h 48m (after reset)

Projected 70% at reset

Burn rate: 16.3%/hr

29day streak

Last 30 Days

7-Day Usage

Today: 22%

MonTueWedThuFriSatSun

Updated just now

Quit

38% · 1h 59m

Battery

Session (5-hour)

38%used

1h 59m remaining

Weekly (7-day)26% used

Resets on Sunday, Feb 15 at 3:00 PM

Extra Usage56%

$56.46 / $100.00$43.54 remaining

Projections

Increasing

Limit in 3h 48m (after reset)

Projected 70% at reset

Burn rate: 16.3%/hr

29day streak

Last 30 Days

7-Day Usage

Today: 22%

MonTueWedThuFriSatSun

Updated just now

Quit

Gauges

Session, weekly, Opus, and extra usage tracking

30d

History

Heatmap, streaks, and daily peak tracking

Dependencies

Native Swift app with minimal resource usage

Accounts

Multi-account support with instant switching

Features

Everything you need to understand and manage your Claude Code API consumption.

Session Gauges

Circular progress rings showing utilization for the 5-hour rate limit window. See percentage used and time remaining at a glance.

Weekly Tracking

Monitor your 7-day rolling window consumption with a progress bar. Know exactly when your weekly limit resets.

Burn Rate Projections

Linear regression on recent snapshots predicts when you'll hit your limit and what your utilization will be at reset.

Usage Streaks & Heatmap

GitHub-style contribution heatmap showing 30-day activity patterns. Track your daily coding streak with a flame counter.

Multi-Account Support

Manage up to 5 Claude accounts and switch between them seamlessly. Per-account state caching preserves context.

Session Detection

Integrates with Claude Code hooks to detect active coding sessions. Polls faster when you're working, slower when idle.

What It Tracks

Four distinct usage dimensions, each with its own gauge and detailed metrics. Battery monitors everything the Anthropic API exposes.

Session

5-Hour Window

Tracks your rate limit consumption within the current 5-hour session. Shows percentage used, time remaining, and a circular progress ring that fills as you consume capacity.

Utilization %Current usage as a percentage of your session limit

Time remainingCountdown until the 5-hour window resets

Time since resetHow long since your last session window started

Weekly

7-Day Window

Monitors your rolling 7-day usage with a progress bar. Includes the exact reset date and time so you can plan longer coding sessions around your weekly capacity.

Weekly %Usage across the full 7-day rolling window

Reset dateExact day and time your weekly limit resets

RemainingPercentage of weekly capacity still available

Opus

Opus Model Usage

Separate tracking for Claude Opus model usage, which has its own rate limits on Max and Max 5x plans. Only appears when your plan includes Opus access.

Opus %Current Opus-specific utilization

WindowOpus rate limit window (varies by plan)

AvailabilityPlan-dependent visibility

Extra Usage

Spending Monitor

Tracks overuse credits and monthly spending when extra usage is enabled. Shows dollar amounts spent, your configured limit, and remaining budget.

Amount spentCurrent month's extra usage charges

Spending limitYour configured monthly maximum

RemainingBudget left before hitting the cap

Predictive Intelligence

Battery doesn't just show current usage - it predicts the future. Linear regression on recent snapshots calculates your burn rate and projects when you'll hit limits.

Burn Rate

Percentage points consumed per hour, calculated from recent snapshots

Linear regression · Last 20 snapshots · Min 3 data points

Time to Limit

Predicts exactly when you'll hit 100% based on current consumption rate

Accounts for window resets · Filters stale data

Reset Projection

Projects what your utilization will be when the rate limit window resets

Session window · Weekly window · Trend classification

Smart Polling

Battery adjusts its polling frequency based on whether you're actively coding. Integrates with Claude Code hooks for automatic session detection.

State

Interval

Description

Active session

30 seconds

Fast updates while you're coding

Idle

5 minutes

Low-impact background polling

Session hook detected

30 seconds

Auto-switches when Claude Code starts

Notifications

80%Early warning - start pacing

90%Caution - limit approaching

95%Critical - almost at limit

All thresholds are customizable. Notifications reset when utilization drops.

% + Time

38% · 1h 59m

Full context at a glance

% Only

38%

Minimal, just the number

Time Only

1h 59m

Focus on time remaining

Icon Only

●

Cleanest possible

How It Works

Battery runs as a lightweight menu bar app with no Dock icon. All data stays local on your machine.

Authenticate

OAuth via Claude.ai

Battery uses the same OAuth credentials as Claude Code. Sign in once, tokens refresh automatically.

Poll

Fetch usage data

Queries the Anthropic OAuth usage API at regular intervals. 30s during active sessions, 5m when idle.

Store

Local SQLite database

Snapshots are stored locally with 90-day retention. Enables burn rate calculations and historical stats.

Project

Linear regression

Uses the last 20 snapshots to calculate burn rate and predict when you'll hit your rate limit.

Display

Menu bar popover

Renders circular gauges, progress bars, heatmaps, and charts in a native SwiftUI popover.

Notify

Threshold alerts

Sends macOS notifications when usage crosses configurable thresholds. Resets when utilization drops.

Get Started

Install via Homebrew or download the DMG directly. Battery authenticates via OAuth using the same credentials as Claude Code.

Homebrew

$ brew tap allthingsclaude/battery

$ brew install --cask claude-battery

Manual

Download DMG from GitHub Releases

Native Swift app. No Electron. No web views. Runs as a menu bar extra with minimal resource usage.

View on GitHub↗

Requirements

macOS 13.0 (Ventura) or later

Claude Code installed and authenticated

Swift 5.9+ (for building from source)

Session Detection Hook

For smarter polling, install the Battery hook in your Claude Code hooks configuration. This enables automatic fast/slow polling based on whether you're actively coding.

SessionStartSwitches to fast polling when Claude Code starts

SessionEndReturns to idle polling when session ends

PostToolUseKeeps session active during tool use

StopMarks session end on explicit stop

Privacy

All data stays local on your machine

Tokens stored with 0600 file permissions

90-day local data retention in SQLite

No telemetry, no cloud sync