CodeBurn

Skill by 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

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

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

Key Commands

# 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 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

# 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:

codeburn uninstall-menubar

Export Examples

# 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

{
  "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:

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)}`);
}

// 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

#!/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

# 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

#!/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"

# 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

# 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

# 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:

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

TUI rendering issues

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

# Force color mode
COLORTERM=truecolor codeburn

Related

• ccusage — inspiration for this project
• LiteLLM — model pricing data source
• SwiftBar — macOS menu bar plugin host