🔥 ccburn

Watch your tokens burn — before you get burned.

TUI and CLI for Claude Code usage limits — burn-up charts, compact mode for status bars, JSON for automation.

Features

• Real-time burn-up charts — Visualize session, weekly, and monthly usage with live-updating terminal graphics
• Pace indicators — 🧊 Cool. 🔥 On pace. 🚨 Too hot.
• Multiple output modes — Full TUI, compact single-line for status bars, or JSON for scripting
• Statusline integration — ccburn collect pipes into your Claude Code statusline for zero-API-call data
• Multi-profile support — Isolated data per Claude Code profile via CLAUDE_CONFIG_DIR
• Automatic data persistence — SQLite-backed history for trend analysis
• Shareable history — ccburn history --json prints that history for other tools, such as the ccburn-mod chart inside Claude Code
• Agent-friendly — ccburn describe outputs structured JSON for AI agents to auto-configure
• Zoom views — Focus on recent activity with --since / --until

Installation

Run claude and login first to refresh credentials.

WinGet (Windows)

winget install JuanjoFuchs.ccburn

npx

npx ccburn

npm

npm install -g ccburn

pip

pip install ccburn

From Source

git clone https://github.com/JuanjoFuchs/ccburn.git
cd ccburn
pip install -e ".[dev]"

Quick Start

Let Claude Code do the setup for you. Paste this in:

Run npx -y ccburn describe and configure ccburn for me using the output.

ccburn describe emits structured JSON with your exact settings.json path, the before/after statusline snippet, multi-profile notes, and the full command reference — everything Claude Code needs to wire up ccburn collect without you reading the rest of this README.

Prefer manual setup? See Manual Setup below.

Why ccburn collect?

ccburn needs usage data, and its default sources are unreliable:

• OAuth API — frequently returns 429 rate limits
• Claude Desktop cookies — only work for the default profile

ccburn collect solves this by reading the rate_limits JSON Claude Code already emits to its statusline (since v2.1.80) and saving it to a local SQLite DB. Zero extra API calls, no rate limits, works with all profiles.

// ~/.claude/settings.json
{
  "statusLine": {
    "command": "ccburn collect | your-existing-statusline-command"
  }
}

ccburn collect passes the original JSON through unchanged, so your existing statusline keeps working.

Manual Setup

1. Run Claude Code first to refresh credentials:

   claude
   

2. Run ccburn:

   ccburn                # Auto-detect best available data
   ccburn session        # 5-hour rolling session limit
   ccburn weekly         # 7-day weekly limit
   ccburn monthly        # Monthly credits (enterprise)
   

3. Set up the statusline — see Why ccburn collect? above.

Usage Examples

# Full TUI with burn-up chart (default)
ccburn

# Specific limit views
ccburn session         # 5-hour session
ccburn weekly          # 7-day weekly
ccburn monthly         # Monthly credits (enterprise)

# Compact output for tmux/status bars
ccburn --compact
# Output: Session: 🔥 45% (2h14m) | Weekly: 🧊 12%

# JSON output for scripting/automation
ccburn --json

# Zoom views
ccburn --since 30m                        # Last 30 minutes
ccburn --since 3d --until end             # Last 3 days through window end
ccburn --since start --until depleted     # Full window through projected depletion

# Single snapshot (no live updates)
ccburn --once

# Custom refresh interval (seconds)
ccburn --interval 10

# AI agent introspection
ccburn describe        # Structured JSON with setup instructions

Multiple Profiles

If you run multiple Claude Code profiles with CLAUDE_CONFIG_DIR, each profile gets isolated data:

# Enterprise profile (default)
ccburn

# Personal profile
CLAUDE_CONFIG_DIR=~/.claude-personal ccburn

Each profile stores its history in a separate database (~/.ccburn/, ~/.ccburn-personal/, etc.).

Command Line Reference

Commands:
  ccburn                Auto-detect and display best available limit
  ccburn session        5-hour rolling session limit
  ccburn weekly         7-day weekly limit (all models)
  ccburn weekly-sonnet  7-day weekly limit (Sonnet only)
  ccburn monthly        Monthly credit usage (enterprise)
  ccburn collect        Statusline pipe: save usage data to DB, pass through
  ccburn describe       Output structured JSON for AI agents
  ccburn clear-history  Clear all stored usage history

Options:
  -i, --interval INT    Render interval in seconds [default: 5/30/60]
  -p, --poll-interval INT  API poll interval in seconds [default: 60]
  -s, --since TEXT      Time window (e.g., '30m', '2h', '7d', 'start')
  -u, --until TEXT      Display end: 'now', 'end', or 'depleted'
  -j, --json            Output JSON and exit
  -1, --once            Print once and exit (no live updates)
  -c, --compact         Single-line output for status bars
  -d, --debug           Show debug information and strategy used
  -v, --version         Show version and exit
  --help                Show this message and exit

Pace Indicators

Chart Elements

Use --since start --until depleted to see the full window through the projected depletion point.

Requirements

• Python 3.10+
• Claude Code installed with valid credentials
• Terminal with Unicode support (for charts and emojis)

How It Works

ccburn uses multiple strategies to get usage data, in priority order:

1. Statusline cache — Data from ccburn collect in the SQLite DB (recommended, zero API calls)
2. OAuth API — Direct call to api.anthropic.com/api/oauth/usage (may hit 429 rate limits)
3. Claude Desktop cookies — Decrypts cookies and calls the web API via curl (default profile only)
4. DB history fallback — Shows last known data with a staleness banner

It calculates:

• Budget pace — Where you "should" be based on time elapsed in the window
• Burn rate — How fast you're consuming your limit (linear regression)
• Time to limit — Estimated time until you hit 100% (if current rate continues)

Data is stored locally in SQLite for historical analysis and to minimize API calls.

Troubleshooting

"Credentials not found"

Ensure Claude Code is installed and you've logged in at least once:

claude  # This will prompt for login if needed

Chart not displaying correctly

Ensure your terminal supports Unicode and has a monospace font with emoji support. Recommended terminals:

• Windows: Windows Terminal
• macOS: iTerm2, Terminal.app
• Linux: Kitty, Alacritty, GNOME Terminal

Stale data indicator

If you see a yellow "Using cached data" banner, ccburn couldn't reach the API. It will continue showing cached data and retry automatically. Set up ccburn collect in your statusline to avoid this entirely.

Debug mode

Use --debug to see which data strategy is being used and troubleshoot issues. Logs are also written to ~/.ccburn/ccburn.log.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Acknowledgments

• Rich — Beautiful terminal formatting
• Plotext — Terminal plotting
• Typer — CLI framework