Skip to content

Visual polish — cleaner bars, compact outcomes, smarter defaults #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Mahiler1909 merged 1 commit into from
Mar 28, 2026
Merged

Visual polish — cleaner bars, compact outcomes, smarter defaults #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
310 changes: 98 additions & 212 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,276 +1,162 @@
# burnlog

**Know where your Claude Code tokens go. Stop the bleeding.**

[![npm version](https://img.shields.io/npm/v/burnlog)](https://www.npmjs.com/package/burnlog)
[![npm downloads](https://img.shields.io/npm/dm/burnlog)](https://www.npmjs.com/package/burnlog)
[![license](https://img.shields.io/npm/l/burnlog)](./LICENSE)
[![node](https://img.shields.io/node/v/burnlog)](https://nodejs.org)
[![CI](https://github.com/Mahiler1909/burnlog/actions/workflows/ci.yml/badge.svg)](https://github.com/Mahiler1909/burnlog/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/Mahiler1909/burnlog/graph/badge.svg)](https://codecov.io/gh/Mahiler1909/burnlog)

Correlate AI coding assistant token usage with real development work. Reads Claude Code's internal data files (`~/.claude/`) and git history to answer: **where did my tokens go and was it worth it?**

## Why

Claude Code sessions can burn through tokens fast. Without visibility, you're flying blind:

- Which project eats the most budget?
- Did that $50 session actually produce commits?
- Am I wasting tokens on retry loops and abandoned sessions?

burnlog reads the raw data Claude Code already stores and cross-references it with `git log` to give you hard numbers.

## Install

```bash
# From npm
npm install -g burnlog

# Or run without installing
npx burnlog
```

From source:

```bash
git clone https://github.com/Mahiler1909/burnlog.git
cd burnlog
npm install
npm run build
npm link # makes 'burnlog' available globally
<!-- TODO: replace with asciinema/vhs recording -->
```
$ burnlog today

## Quick start
Today's Burn vs Yesterday
═══════════════════════════════════════════════════════
Spent: $18.40 (4 sessions) ▼ $6.20 less
Commits: 7 ▲ 3 more
Efficiency: 74/100 ████████████░░░░░░ ▲ +12 points
Top Waste: Retry loop on auth.ts -$3.20

```bash
burnlog # shows token spend dashboard (last 30 days)
burnlog sessions -s cost # list sessions sorted by cost
burnlog waste # detect wasted token spend
```
$ burnlog waste

## Commands

### `report` — Token spend dashboard (default)

```bash
burnlog report # last 30 days, all projects
burnlog report -p 7d # last 7 days
burnlog report --project myapp # filter by project
burnlog report -f json # JSON output (includes all breakdowns)
```
Waste Report (Last 30 days)
═══════════════════════════════════════════════════════
Total Spend: $200.00
Estimated Waste: $17.40 (8.7%)
Top Waste Type: Debugging Loop ($16.11)

```
Burnlog Report (Last 30 days)
════════════════════════════════════════════════════════════
Total: $199.81 | 12 sessions | 3 projects | 6 commits

By Project
┌─────────┬─────────┬──────────┬─────────┬────────────┬──────────┬────────┬─────────┐
│ Project │ Cost │ Sessions │ Commits │ Lines +/- │ $/Commit │ $/Line │ Outcome │
└─────────┴─────────┴──────────┴─────────┴────────────┴──────────┴────────┴─────────┘
┌──────────────────┬──────────┬────────────────────────────────┐
│ Pattern │ Wasted │ Suggestion │
├──────────────────┼──────────┼────────────────────────────────┤
│ Debugging Loop │ $16.11 │ Break the loop: write a test │
│ Context Rebuild │ $1.29 │ Keep sessions under 45 min │
└──────────────────┴──────────┴────────────────────────────────┘
```

Includes breakdowns by model, goal category, and outcome.
## The problem

### `sessions` — List all sessions
Claude Code sessions can cost $5-$200+. You have no idea where that goes. burnlog reads the data Claude Code already stores (`~/.claude/`) and cross-references it with `git log` to answer:

```bash
burnlog sessions --project myapp
burnlog sessions -s cost -l 10 # top 10 by cost
burnlog sessions -p 7d # last 7 days only
burnlog sessions --all # show all (no limit)
burnlog sessions -f csv # CSV export
```

Shows each session with ID, date, project, branch, cost, token count, outcome, and summary.
- Which project eats the most budget?
- Did that $50 session actually produce commits?
- Am I stuck in retry loops burning tokens for nothing?
- What's my efficiency trend this week vs last?

### `session <id>` — Deep dive into a single session
## Try it now

```bash
burnlog session 3dc22f18 # prefix match works
burnlog session 3dc22f18 -f json
npx burnlog
```

Shows full session detail including:
- Token usage breakdown (input, output, cache)
- Activity stats (lines, files, commits)
- Exchange-level log (each prompt/response with cost, model, tools used)
- Waste signals detected in the session
- Correlated git commits
That's it. No config, no setup. If you've used Claude Code, you already have data.

### `branch <name>` — Cost breakdown for a feature branch
## Install

```bash
burnlog branch feat/US-402
burnlog branch main --project myapp
npm install -g burnlog
```

Correlates sessions with git commits on the branch. Shows total cost, $/commit, $/line changed, and waste ratio.
## Commands

### `waste` — Detect wasted token spend
### Daily workflow

```bash
burnlog waste # last 30 days
burnlog waste -p 7d --project myapp
```
| Command | What it does |
|---------|-------------|
| `burnlog today` | Quick daily summary with vs-yesterday comparison and efficiency score |
| `burnlog budget` | Track spending against daily/weekly/monthly limits with projections |
| `burnlog budget set --daily 25 --monthly 500` | Configure your budget limits |
| `burnlog trends` | 4-week trend analysis with sparklines and efficiency scores |

```
Burnlog Waste Report (Last 30 days)
════════════════════════════════════════════════════════════
Total Spend: $200.00
Estimated Waste: $17.40 (8.7%)
Top Waste Type: Debugging Loop ($16.11)
```
### Analysis

Detects patterns like:
- **Retry Loop** — same tool called repeatedly with errors
- **Debugging Loop** — consecutive fix attempts on the same file
- **Abandoned Session** — high-cost session with no output
- **Context Rebuild** — expensive cache rebuilds from long sessions
- **Excessive Exploration** — too many reads with no edits
- **Error Cascade** — chain of tool failures
- **Stalled Exploration** — high read-to-write ratio
- **Wrong Approach** — approach that needed to be rethought
| Command | What it does |
|---------|-------------|
| `burnlog` | Token spend dashboard — last 30 days, broken down by project/model/outcome |
| `burnlog sessions -s cost -l 10` | Top 10 most expensive sessions |
| `burnlog session <id>` | Deep dive: exchange log, waste signals, correlated commits |
| `burnlog waste` | Detect wasted spend with actionable suggestions |
| `burnlog branch feat/US-402` | Cost breakdown for a feature branch ($/commit, $/line) |
| `burnlog compare feat/US-402 fix/US-411` | Side-by-side efficiency comparison between branches |

### `compare <branchA> <branchB>` — Compare branch efficiency
All commands support `--period` (7d, 30d, 90d), `--project`, and `-f json|csv|table`.

```bash
burnlog compare feat/US-402 fix/US-411 --project myapp
```
## What it detects

Side-by-side comparison of cost, commits, lines changed, $/commit, and waste ratio. Use `--project` when you have multiple projects with the same branch names.
burnlog identifies 9 waste patterns and tells you how to fix them:

## Export formats
| Pattern | What's happening | Suggestion |
|---------|-----------------|------------|
| **Retry Loop** | 3+ consecutive same-file edits with similar prompts | Break the loop — describe what's wrong differently |
| **Debugging Loop** | 4+ consecutive fix attempts on the same files | Write a failing test first, then let Claude fix it |
| **Abandoned Session** | High-cost session with no commits | Start smaller — break the task into pieces |
| **Context Rebuild** | Expensive cache rebuilds mid-session | Keep sessions under 45 min to avoid context rot |
| **Excessive Exploration** | 70%+ read-only exchanges, no edits | Be specific about what you want changed |
| **Error Cascade** | Chain of consecutive tool failures | Check errors early — don't let Claude spiral |
| **Stalled Exploration** | Repeated "continue" prompts with no progress | Redirect with a concrete next step |
| **Wrong Approach** | Approach needed to be rethought mid-session | Spend 2 min planning before starting a session |
| **High Cost/Line** | >$1/line on expensive sessions | Check if generated code was actually needed |

All commands support `-f, --format`:
## Efficiency score

| Format | Flag | Use case |
|--------|------|----------|
| Table | `-f table` (default) | Terminal viewing |
| JSON | `-f json` | Piping to `jq`, dashboards, automation |
| CSV | `-f csv` | Spreadsheets, data analysis |
Each session and period gets a **0-100 efficiency score** combining:

```bash
burnlog report -f json | jq '.byProject[] | select(.cost > 10)'
burnlog sessions --project myapp -f csv > sessions.csv
```
| Component | Weight | What it measures |
|-----------|--------|-----------------|
| Outcome | 35% | Did the session achieve its goal? |
| Waste ratio | 25% | What % of spend was wasted? |
| Cost efficiency | 20% | $/commit — lower is better |
| Cache hit rate | 20% | How well prompts reused context? |

## Reading the numbers

### $/Commit

How much each git commit cost in tokens. Lower is more efficient.

| Range | Interpretation |
|-------|---------------|
| Range | Meaning |
|-------|---------|
| < $5 | Very efficient — quick, focused changes |
| $5–$15 | Normal — typical feature work |
| $15–$30 | Expensive — complex tasks or some back-and-forth |
| > $30 | Investigate — possible retry loops or overexploration |

### $/Line

Cost per line of code changed (added + removed). Context-dependent — a 1-line bug fix may cost more per line than scaffolding 500 lines.
| $5-$15 | Normal — typical feature work |
| $15-$30 | Expensive — complex tasks or back-and-forth |
| > $30 | Investigate — possible retry loops |

### Waste ratio

Percentage of session cost attributed to detected waste patterns.

| Range | Interpretation |
|-------|---------------|
| < 10% | Good — minimal waste |
| 10–25% | Normal — some inefficiency is expected |
| > 25% | High — review waste signals for actionable tips |

### Outcome

How well the session achieved its goal:

| Value | Meaning |
| Range | Meaning |
|-------|---------|
| `fully_achieved` | Task completed successfully |
| `mostly_achieved` | Task completed with minor gaps |
| `partially_achieved` | Some progress but incomplete |
| `not_achieved` | Task not completed |
| `unknown` | Short or planning-only sessions |

## How it works

### Data sources

burnlog reads from `~/.claude/projects/`:

| Source | What it provides |
|--------|-----------------|
| `sessions-index.json` | Session list with IDs, paths, branches |
| JSONL conversations | Token usage per exchange, tools used, files modified |
| `usage-data/facets/*.json` | Goals, outcomes, satisfaction (when available) |
| `usage-data/session-meta/*.json` | Aggregated stats per session |

### Git correlation

Sessions are matched to git commits using a 3-tier strategy:

1. **Branch name match** — session's branch matches commit's branch (highest confidence)
2. **Temporal match** — commit timestamp falls within session start/end +2 hours
3. **File overlap** — basename overlap between session's modified files and commit's changed files

### Outcome inference

When Claude Code's facets data isn't available, burnlog infers outcomes from exchange patterns:

- **fully_achieved** — has implementation exchanges, produced changes, no errors
- **partially_achieved** — produced changes but had errors or interruptions
- **not_achieved** — many exchanges but no implementation, or errors with no output
- **unknown** — short or planning-only sessions

## Troubleshooting
| < 10% | Good — minimal waste |
| 10-25% | Normal — some inefficiency is expected |
| > 25% | High — check `burnlog waste` for tips |

### "No sessions found"
## Export & automation

- burnlog reads data from `~/.claude/`. Make sure you've used Claude Code at least once.
- Check your `--period` filter — the default is 30 days. Use `-p 90d` for a wider window.
- Check your `--project` filter — it matches project names and paths (case-insensitive, partial match).
```bash
# Pipe to jq for custom queries
burnlog report -f json | jq '.byProject[] | select(.cost > 10)'

### Git repo not found
# Export to CSV for spreadsheets
burnlog sessions -f csv > sessions.csv

- burnlog resolves git repos from the project paths stored in `~/.claude/`. If a project directory was moved or deleted, git correlation won't work for that project.
- Git correlation is optional — token and cost data still shows without git.
# Daily spend check in your shell profile
alias burn="npx burnlog today"
```

### Empty token counts
## How it works

- Older Claude Code versions may not log detailed usage data. burnlog falls back to session-meta when JSONL data is incomplete.
burnlog reads from `~/.claude/projects/` (session indexes, JSONL conversation logs, facets, and session metadata). It correlates sessions to git commits using a 3-tier strategy:

## Architecture
1. **Branch match** — session branch = commit branch (highest confidence)
2. **Temporal match** — commit within session time window (±2 hours)
3. **File overlap** — modified files in session overlap with commit diffs

```
src/
├── index.ts # CLI entry (commander.js)
├── data/models.ts # TypeScript interfaces
├── providers/
│ ├── provider.interface.ts # Provider contract
│ └── claude-code/provider.ts # Reads ~/.claude/ data files
├── core/
│ ├── token-ledger.ts # Token counting and cost calculation
│ ├── correlation-engine.ts # Git ↔ session matching
│ └── insights-engine.ts # Waste pattern detection
├── git/
│ └── git-analyzer.ts # Git log, branch, diff operations
├── cli/
│ ├── commands/ # One file per command
│ └── formatters/
│ ├── table.ts # Terminal table rendering
│ └── export.ts # JSON/CSV output
└── utils/
├── pricing-tables.ts # Model pricing data
├── period.ts # Time period parsing
└── filters.ts # Shared session filters
```
No data leaves your machine. Everything is local, read-only.

## Requirements

- Node.js >= 18
- Claude Code installed (data lives in `~/.claude/`)
- Git (for commit correlation)
- Claude Code installed (data in `~/.claude/`)
- Git (for commit correlation — optional)

## License

Expand Down
Loading
Loading