codeburn-claude-cost-dashboard

What this skill does

# CodeBurn

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

CodeBurn is an interactive TUI dashboard that reads Claude Code session transcripts directly from disk (`~/.claude/projects/`) and visualizes token usage, costs, and task breakdowns by project, model, activity type, MCP server, and tool. No API keys, no proxy — pure local file analysis.

## Install

```bash
npm install -g codeburn
# or run without installing
npx codeburn
```

**Requirements:** Node.js 20+, Claude Code installed (session data at `~/.claude/projects/`)

## Key Commands

```bash
# Interactive TUI dashboard (default: last 7 days)
codeburn

# Time period shortcuts
codeburn today
codeburn month
codeburn report -p month      # explicit period flag

# Compact one-liner summary
codeburn status
codeburn status --format json

# Export data
codeburn export               # CSV: today, 7d, 30d
codeburn export -f json       # JSON export

# macOS menu bar widget (requires SwiftBar)
codeburn install-menubar
codeburn uninstall-menubar
```

### TUI Keyboard Navigation

| Key | Action |
|-----|--------|
| `←` `→` arrow keys | Switch between Today / 7 Days / Month |
| `1` `2` `3` | Period shortcuts |
| `q` | Quit |

## What CodeBurn Tracks

### 13 Task Categories (deterministic, no LLM calls)

| Category | Trigger Pattern |
|---|---|
| Coding | Edit, Write tools |
| Debugging | Error/fix keywords + tool usage |
| Feature Dev | "add", "create", "implement" keywords |
| Refactoring | "refactor", "rename", "simplify" |
| Testing | pytest, vitest, jest in Bash |
| Exploration | Read, Grep, WebSearch without edits |
| Planning | EnterPlanMode, TaskCreate tools |
| Delegation | Agent tool spawns |
| Git Ops | git push/commit/merge in Bash |
| Build/Deploy | npm build, docker, pm2 |
| Brainstorming | "brainstorm", "what if", "design" |
| Conversation | No tools, pure text exchange |
| General | Skill tool, uncategorized |

### One-Shot Rate
For edit-heavy categories, CodeBurn detects Edit → Bash → Edit retry cycles. The **1-shot rate** shows what percentage of edit turns succeeded without retries. 90% means the AI got it right first try 9/10 times.

### Pricing
Fetched from [LiteLLM](https://github.com/BerriAI/litellm) model prices, auto-cached 24h at `~/.cache/codeburn/`. Covers input, output, cache write, cache read, and web search costs. Falls back to hardcoded prices if fetch fails.

## Data Source

Claude Code stores session transcripts as JSONL:
```
~/.claude/projects/<sanitized-path>/<session-id>.jsonl
```

Each assistant entry contains: model name, token usage (input/output/cache_read/cache_write), tool_use blocks, timestamps. CodeBurn deduplicates by API message ID to prevent double-counting across sessions.

## macOS Menu Bar Setup

```bash
# 1. Install SwiftBar
brew install --cask swiftbar

# 2. Install the CodeBurn plugin
codeburn install-menubar

# 3. Launch SwiftBar — CodeBurn flame icon appears in menu bar
# Refreshes every 5 minutes, shows today's cost + breakdown dropdown
```

To remove:
```bash
codeburn uninstall-menubar
```

## Export Examples

```bash
# Export CSV (three sheets: today, 7d, 30d)
codeburn export
# Output: codeburn-export-2026-04-14.csv

# Export JSON
codeburn export -f json
# Output: codeburn-export-2026-04-14.json
```

### JSON Export Structure

```json
{
  "exported_at": "2026-04-14T10:00:00Z",
  "periods": {
    "today": {
      "total_cost": 1.42,
      "total_tokens": 284000,
      "by_project": { "my-app": 0.89, "other-project": 0.53 },
      "by_model": { "claude-sonnet-4-5": 1.10, "claude-opus-4-5": 0.32 },
      "by_activity": {
        "Coding": { "cost": 0.65, "turns": 34, "one_shot_rate": 0.88 },
        "Debugging": { "cost": 0.41, "turns": 18, "one_shot_rate": 0.72 }
      }
    },
    "7d": { ... },
    "30d": { ... }
  }
}
```

## Project Structure

```
src/
  cli.ts          # Commander.js entry point
  dashboard.tsx   # Ink TUI (React for terminals)
  parser.ts       # JSONL reader, dedup, date filter
  models.ts       # LiteLLM pricing, cost calculation
  classifier.ts   # 13-category task classifier
  types.ts        # Type definitions
  format.ts       # Text rendering (status bar)
  menubar.ts      # SwiftBar plugin generator
  export.ts       # CSV/JSON multi-period export
```

## Programmatic Usage (TypeScript)

If you want to integrate CodeBurn's parsing logic into your own scripts:

```typescript
import { parseSessions } from 'codeburn/parser';
import { calculateCost } from 'codeburn/models';
import { classifyTurn } from 'codeburn/classifier';

// Parse all sessions for a date range
const sessions = await parseSessions({
  startDate: new Date('2026-04-01'),
  endDate: new Date('2026-04-14'),
});

// Sessions are deduplicated by API message ID
for (const turn of sessions.turns) {
  const category = classifyTurn(turn);
  const cost = await calculateCost(turn.model, turn.usage);
  console.log(`${category}: $${cost.toFixed(4)}`);
}
```

```typescript
// Get a status summary programmatically
import { getStatus } from 'codeburn/format';

const status = await getStatus();
console.log(status);
// → "🔥 Today: $1.42 (284k tokens) | Month: $18.30 (3.6M tokens)"

// JSON format for scripting
const statusJson = await getStatus({ format: 'json' });
const data = JSON.parse(statusJson);
// { today: { cost: 1.42, tokens: 284000 }, month: { cost: 18.30, tokens: 3600000 } }
```

## Common Patterns

### Daily Cost Check in CI/Shell Scripts

```bash
#!/bin/bash
# Add to .zshrc or run in CI to log daily AI spend
SPEND=$(codeburn status --format json | jq '.today.cost')
echo "Today's Claude spend: \$$SPEND"

# Alert if over threshold
if (( $(echo "$SPEND > 5.00" | bc -l) )); then
  echo "⚠️  High AI spend today: \$$SPEND"
fi
```

### Export and Analyze with jq

```bash
# Export JSON and analyze by model
codeburn export -f json | jq '.periods["7d"].by_model'

# Find most expensive project this month
codeburn export -f json | jq '
  .periods["30d"].by_project
  | to_entries
  | sort_by(-.value)
  | .[0]
'
```

### Automate Weekly Reports

```bash
#!/bin/bash
# weekly-ai-report.sh — run via cron on Mondays
OUTPUT_DIR="$HOME/ai-cost-reports"
mkdir -p "$OUTPUT_DIR"

DATE=$(date +%Y-%m-%d)
codeburn export -f json > "$OUTPUT_DIR/week-$DATE.json"
codeburn status >> "$OUTPUT_DIR/history.log"
echo "[$DATE] Report saved to $OUTPUT_DIR/week-$DATE.json"
```

## Troubleshooting

### No data shown / "No sessions found"

```bash
# Verify Claude Code session files exist
ls ~/.claude/projects/

# Check a specific project's sessions
ls ~/.claude/projects/<project-name>/
# Should see *.jsonl files

# Confirm Node version is 20+
node --version
```

### Pricing fetch fails / shows $0.00

```bash
# Clear the price cache and retry
rm -rf ~/.cache/codeburn/

# CodeBurn falls back to hardcoded prices automatically
# Run again — it will re-fetch from LiteLLM
codeburn today
```

### Menu bar widget not updating

```bash
# Reinstall the plugin
codeburn uninstall-menubar
codeburn install-menubar

# Ensure SwiftBar is running and plugin directory is set
# SwiftBar → Preferences → Plugin folder should point to ~/Library/Application Support/SwiftBar/Plugins/
```

### Double-counted costs

CodeBurn deduplicates by API message ID automatically. If you see unexpectedly high numbers, check for duplicate JSONL files:

```bash
# List all session files sorted by size
find ~/.claude/projects/ -name "*.jsonl" | xargs wc -l | sort -rn | head -20
```

### TUI rendering issues

```bash
# Ensure terminal supports 256 colors
echo $TERM
# Should be xterm-256color or similar

# Force color mode
COLORTERM=truecolor codeburn
```

## Related

- [ccusage](https://github.com/ryoppippi/ccusage) — inspiration for this project
- [LiteLLM](https://github.com/BerriAI/litellm) — model pricing data source
- [SwiftBar](https://github.com/swiftbar/SwiftBar) — macOS menu bar plugin host