ccburn JuanjoFuchs
Use this command to install ccburn:
winget install --id=JuanjoFuchs.ccburn -e 🔥 Claude Code usage limits — TUI with burn-up charts, compact mode for status bars, JSON for automation
Loading...
README
🔥 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 and weekly 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
- Automatic data persistence — SQLite-backed history for trend analysis
- Dynamic window title — Terminal tab shows current usage at a glance
- Zoom views — Focus on recent activity with
--since
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
- Run Claude Code first to ensure credentials are fresh:
claude - Run ccburn:
ccburn # Session limit (default) ccburn weekly # Weekly limit ccburn weekly-sonnet # Weekly Sonnet limit
Usage Examples
# Full TUI with burn-up chart (default)
ccburn
# Weekly usage view
ccburn weekly
# Compact output for tmux/status bars
ccburn --compact
# Output: Session: 🔥 45% (2h14m) | Weekly: 🧊 12% | Sonnet: 🧊 3%
# JSON output for scripting/automation
ccburn --json
# Zoom to last 30 minutes
ccburn --since 30m
# Single snapshot (no live updates)
ccburn --once
# Custom refresh interval (seconds)
ccburn --interval 10
Command Line Reference
Usage: ccburn [OPTIONS] [LIMIT]
Arguments:
[LIMIT] Which limit to display [default: session]
Options: session, weekly, weekly-sonnet
Options:
-i, --interval INTEGER Refresh interval in seconds [default: 5/30]
-s, --since TEXT Only show data since (e.g., 30m, 2h, 1d)
-j, --json Output JSON and exit
-o, --once Print once and exit (no live updates)
-c, --compact Single-line output for status bars
--debug Show debug information
--version Show version and exit
--help Show this message and exit
Pace Indicators
| Emoji | Status | Meaning |
|---|---|---|
| 🧊 | Behind pace | Usage below expected budget — you have headroom |
| 🔥 | On pace | Usage tracking with expected budget |
| 🚨 | Ahead of pace | Usage above expected budget — slow down! |
Requirements
- Python 3.10+
- Claude Code installed with valid credentials
- Terminal with Unicode support (for charts and emojis)
How It Works
ccburn reads your Claude Code credentials and fetches usage data from the Anthropic API. It calculates:
- Budget pace — Where you "should" be based on time elapsed in the window
- Burn rate — How fast you're consuming your limit
- 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 when running multiple instances.
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 "(stale)" in the header, ccburn couldn't reach the API. It will continue showing cached data and retry automatically.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.