theirongolddev/cburn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
cburn/README.md
teernisse 0e80a6c1d1 docs(readme): document daemon mode and HTTP/SSE API 
Update README with daemon usage:
- Add daemon to quick start examples
- Add daemon row to CLI commands table
- Document all HTTP endpoints with usage examples
- Add internal/daemon to package map

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-28 00:05:11 -05:00

230 lines
6.4 KiB
Markdown
Raw Permalink Blame History

# cburn
A CLI and TUI dashboard for analyzing Claude Code usage metrics. Parses JSONL session logs from `~/.claude/projects/`, computes token usage, costs, cache efficiency, and activity patterns.
## Installation
```bash
go install github.com/theirongolddev/cburn@latest
```
Or build from source:
```bash
git clone https://github.com/theirongolddev/cburn.git
cd cburn
make install
```
Requires Go 1.24+.
**Note:** Ensure `~/go/bin` is in your PATH:
```bash
# bash/zsh: add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/go/bin:$PATH"
# fish: add to ~/.config/fish/config.fish
fish_add_path ~/go/bin
```
## Quick Start
```bash
cburn # Summary of usage metrics
cburn tui # Interactive dashboard
cburn costs # Cost breakdown by token type
cburn status # Claude.ai subscription status
cburn daemon --detach # Background usage daemon + local API
```
## CLI Commands
| Command | Description |
|---------|-------------|
| `cburn` | Usage summary (default) |
| `cburn summary` | Detailed usage summary with costs |
| `cburn costs` | Cost breakdown by token type and model |
| `cburn daily` | Daily usage table |
| `cburn hourly` | Activity by hour of day |
| `cburn sessions` | Session list with details |
| `cburn models` | Model usage breakdown |
| `cburn projects` | Project usage ranking |
| `cburn status` | Claude.ai subscription status and rate limits |
| `cburn daemon` | Background daemon with JSON/SSE usage API |
| `cburn config` | Show current configuration |
| `cburn setup` | Interactive first-time setup wizard |
| `cburn tui` | Interactive dashboard |
## Global Flags
```
-n, --days INT Time window in days (default: 30)
-p, --project STRING Filter to project (substring match)
-m, --model STRING Filter to model (substring match)
-d, --data-dir PATH Claude data directory (default: ~/.claude)
-q, --quiet Suppress progress output
--no-cache Skip SQLite cache, reparse everything
--no-subagents Exclude subagent sessions
```
**Examples:**
```bash
cburn -n 7 # Last 7 days
cburn costs -p myproject # Costs for a specific project
cburn sessions -m opus # Sessions using Opus models
cburn daily --no-subagents # Exclude spawned agents
cburn daemon --detach # Start daemon in background
cburn daemon status # Check daemon health and latest totals
cburn daemon stop # Stop daemon
```
## Daemon Mode
`cburn daemon` runs a long-lived polling service that keeps usage snapshots warm and exposes local endpoints for downstream tools.
Default endpoint: `http://127.0.0.1:8787`
- `GET /healthz` - liveness probe
- `GET /v1/status` - current aggregate snapshot and daemon runtime status
- `GET /v1/events` - recent event buffer (JSON array)
- `GET /v1/stream` - Server-Sent Events stream (`snapshot`, `usage_delta`)
Example:
```bash
cburn daemon --detach --interval 10s
curl -s http://127.0.0.1:8787/v1/status | jq
```
## TUI Dashboard
Launch with `cburn tui`. Navigate with keyboard:
| Key | Action |
|-----|--------|
| `o` / `c` / `s` / `b` / `x` | Jump to Overview / Costs / Sessions / Breakdown / Settings |
| `<-` / `->` | Previous / Next tab |
| `j` / `k` | Navigate lists |
| `J` / `K` | Scroll detail pane |
| `Ctrl+d` / `Ctrl+u` | Scroll half-page |
| `Enter` / `f` | Expand session full-screen |
| `Esc` | Back to split view |
| `r` | Refresh data |
| `R` | Toggle auto-refresh |
| `?` | Help overlay |
| `q` | Quit |
### Tabs
- **Overview** - Summary stats, daily activity chart, live hourly/minute charts
- **Costs** - Cost breakdown by token type and model, cache savings
- **Sessions** - Browseable session list with detail pane
- **Breakdown** - Model and project rankings
- **Settings** - Configuration management
### Themes
Four color themes are available:
- `flexoki-dark` (default) - Warm earth tones
- `catppuccin-mocha` - Pastel colors
- `tokyo-night` - Cool blue/purple
- `terminal` - ANSI 16 colors only
Change via `cburn setup` or edit `~/.config/cburn/config.toml`.
## Configuration
Config file: `~/.config/cburn/config.toml`
```toml
[general]
default_days = 30
include_subagents = true
[claude_ai]
session_key = "sk-ant-sid..." # For subscription/rate limit data
[admin_api]
api_key = "sk-ant-admin-..." # For billing API (optional)
[appearance]
theme = "flexoki-dark"
[budget]
monthly_usd = 100 # Optional spending cap
[tui]
auto_refresh = true
refresh_interval_sec = 30
```
### Environment Variables
| Variable | Description |
|----------|-------------|
| `CLAUDE_SESSION_KEY` | Claude.ai session key (overrides config) |
| `ANTHROPIC_ADMIN_KEY` | Admin API key (overrides config) |
### Claude.ai Session Key
The session key enables:
- Real-time rate limit monitoring (5-hour and 7-day windows)
- Overage spend tracking
- Organization info
To get your session key:
1. Open claude.ai in your browser
2. DevTools (F12) > Application > Cookies > claude.ai
3. Copy the `sessionKey` value (starts with `sk-ant-sid...`)
## Caching
Session data is cached in SQLite at `~/.cache/cburn/metrics_v2.db`. The cache uses mtime-based diffing - unchanged files are not reparsed.
Force a full reparse with `--no-cache`.
## Development
```bash
make build # Build ./cburn binary
make install # Install to ~/go/bin
make lint # Run golangci-lint
make test # Run unit tests
make test-race # Tests with race detector
make bench # Pipeline benchmarks
make fuzz # Fuzz the JSONL parser (30s default)
make clean # Remove binary and test cache
```
## Architecture
```
~/.claude/projects/**/*.jsonl
-> source.ScanDir() + source.ParseFile() (parallel parsing)
-> store.Cache (SQLite, mtime-based incremental)
-> pipeline.Aggregate*() functions
-> CLI renderers (cmd/) or TUI tabs (internal/tui/)
```
| Package | Role |
|---------|------|
| `cmd/` | Cobra CLI commands |
| `internal/source` | File discovery and JSONL parsing |
| `internal/pipeline` | ETL orchestration and aggregation |
| `internal/store` | SQLite cache layer |
| `internal/model` | Domain types |
| `internal/config` | TOML config and pricing tables |
| `internal/daemon` | Background polling daemon + local HTTP/SSE API |
| `internal/cli` | Terminal formatting |
| `internal/claudeai` | Claude.ai API client |
| `internal/tui` | Bubble Tea dashboard |
| `internal/tui/components` | Reusable TUI components |
| `internal/tui/theme` | Color schemes |
## License
MIT
Reference in New Issue View Git Blame Copy Permalink