claude-usage-rs

Tracks Claude promotional usage windows so you know when you're getting 2x and when you're not.

Anthropic is running a promo currently (at the time of writing this tool) where you have access to "doubled usage outside peak hours." This tool watches the clock and bolts onto your shell prompt, tmux, and Claude Code status bar.

Config-driven. New promotions go in ~/.claude/usage-windows.json. No code changes needed.

Claude Code status bar:

⚡ 2x OFF-PEAK  ends in 7h 59m
Opus 4.6 (1M context) │ █░░░░░░░ 12% │ sess 45.6k │ day 123k │ wk 890k │ ~$19.09

Status check:

$ claude-usage
🟢 API: All Systems Operational (just now)
🟢 Off-peak (2x) (2x usage)
   Ends in:      7h 55m
   Promo: March 2026 2x Promo (ends in 12d 1h)

Defer decision:

$ claude-usage defer large
✅ PROCEED: large at 2x (already in favorable window)

Homebrew:

brew tap abhay/tap
brew install claude-usage

Shell installer (macOS / Linux):

curl -fsSL https://raw.githubusercontent.com/abhay/claude-usage-rs/main/install.sh | sh

From source:

cargo install --path .

claude-usage init

Writes usage-windows.json, registers the statusline, and sets up the MCP server. If you have multiple ~/.claude* directories, init finds and configures all of them automatically.

To target a specific instance:

CLAUDE_CONFIG_DIR=~/.claude-work claude-usage init

claude-usage              # human-readable status (includes API health)
claude-usage api-status   # check Anthropic API status
claude-usage label        # compact PS1/Starship token: ⚡2x
claude-usage tmux         # tmux status bar segment
claude-usage statusline   # Claude Code status bar (reads JSON from stdin)
claude-usage json         # machine-readable JSON
claude-usage windows      # list all configured windows
claude-usage de