claude-usage

CLI tool to track your Claude Code subscription usage with sparkline graphs.

Claude Usage Tracker
Updated: Jan 24, 4:55pm

5-hour window
  ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▂▂▂ 15%
  Resets: 6:00pm

7-day window
  ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁ 6%
  Resets: Thu at 10:00am

Requirements

• macOS (uses Keychain for credentials)
• Claude Code CLI installed and logged in
• Claude Pro, Max, or Team subscription

Installation

go install github.com/henryaj/claude-usage@latest

Or build from source:

git clone https://github.com/henryaj/claude-usage
cd claude-usage
go build -o claude-usage .

Usage

# One-shot display
claude-usage

# Compact one-line output
claude-usage --compact
# Output: 5h: 15%  7d: 6%

# Watch mode (polls every 5 minutes)
claude-usage --watch

# Custom polling interval
claude-usage --watch --interval 2m

How it works

1. Reads OAuth credentials from macOS Keychain (stored by Claude Code)
2. Fetches usage data from Anthropic's OAuth usage API
3. Stores historical data in ~/.config/claude-usage/history.json
4. Displays sparkline graphs showing usage over time

Colors

• Green: < 50% usage
• Yellow: 50-80% usage
• Red: > 80% usage