BurnRate Documentation

BurnRate is an AI usage analytics tool that tracks costs, tokens, and usage patterns across 7 AI coding providers. It runs locally on your machine, reads your existing session data, and serves a real-time analytics dashboard. Your data never leaves your machine.

Installation

macOS (Homebrew)

The fastest way to install BurnRate on macOS:

brew install burnrate-dev/tap/burnrate

Linux

Download the latest release for your architecture:

# AMD64
curl -L https://github.com/burnrate-dev/burnrate/releases/latest/download/burnrate_linux_amd64.tar.gz | tar xz
sudo mv burnrate /usr/local/bin/

# ARM64
curl -L https://github.com/burnrate-dev/burnrate/releases/latest/download/burnrate_linux_arm64.tar.gz | tar xz
sudo mv burnrate /usr/local/bin/

Windows

Download the latest .exe from the releases page and add it to your PATH. Or use scoop:

scoop install burnrate

From Source

Requires Go 1.24+:

git clone https://github.com/burnrate-dev/burnrate.git
cd burnrate
make build
./burnrate

First Run

After installing, simply run:

burnrate

BurnRate will automatically:

1. Detect which AI coding tools you have installed
2. Parse your local session data from each provider
3. Launch an analytics dashboard at http://localhost:8089
4. Open the dashboard in your default browser

Setup Wizard

For a guided setup with plan configuration and license activation:

burnrate setup

The wizard walks you through:

• Plan selection — Choose your current AI subscription plan (e.g., Claude Max 5x, Max 20x, Cursor Pro) so BurnRate can calculate your value multiplier
• License key entry — If you have a Pro or Team license key, enter it here to unlock all features
• Provider detection — Confirms which providers were found on your system

Configuration

BurnRate stores its configuration at ~/.burnrate/config.json. You can edit this file directly or use burnrate config to view the current settings.

{
  "plan": "max20x",
  "planCost": 240,
  "providers": "auto",
  "port": 8089,
  "licenseKey": "",
  "providerPlans": {
    "cursor": "cursor-pro"
  },
  "notifications": {
    "enabled": true,
    "budgetAlerts": true,
    "dailySummary": true
  },
  "projectBudgets": {},
  "teamSync": false,
  "teamCode": ""
}

Supported Providers

BurnRate reads session data from 7 AI coding tools. No API keys or credentials are needed — it reads the local files each tool already creates on your machine.

Claude Code

BurnRate reads Claude Code's JSONL session files, which provide the richest data of any provider: full token counts (input, output, cache read, cache create), tool call names, model identification, and subagent tracking.

Data directory

~/.claude/projects/

File format

JSONL — one event per line per session

Subagent support

Full — reads subagents/agent-{id}.jsonl files and links to parent sessions

Rate limits

Real-time via Anthropic OAuth API (5-hour, 7-day, per-model windows)

Platforms

macOS, Linux, Windows

Cursor IDE

BurnRate reads Cursor's local SQLite tracking database. Cursor tracks code generation events as hashed entries rather than full token counts.

Data file

~/.cursor/ai-tracking/ai-code-tracking.db

macOS path

~/Library/Application Support/Cursor/

Linux path

~/.config/Cursor/

Windows path

%APPDATA%\Cursor\

Limitation

No direct token counts — uses code hash count as proxy for API usage

GitHub Copilot

BurnRate reads Copilot's chat session data stored in VS Code's extension state database.

Data file

state.vscdb in github.copilot or github.copilot-chat extension storage

macOS path

~/Library/Application Support/Code/User/globalStorage/github.copilot*/

Linux path

~/.config/Code/User/globalStorage/github.copilot*/

Windows path

%APPDATA%\Code\User\globalStorage\github.copilot*\

Default model

gpt-4o (when model field is empty)

Windsurf

Windsurf stores chat data similarly to VS Code extensions, with rich token and tool call data.

Data file

state.vscdb in workspace and global storage directories

macOS path

~/Library/Application Support/Windsurf/User/

Linux path

~/.config/Windsurf/User/

Windows path

%APPDATA%\Windsurf\User\

Features

Full cache metrics (read + create), tool call tracking per message

Aider

Aider writes structured analytics to a JSONL log file. BurnRate also supports a fallback parser for older Markdown chat history files.

Primary data

~/.aider/analytics.jsonl — structured events with token counts and costs

Fallback data

.aider.chat.history.md files in project directories (limited: no token data)

Note

Aider uses API keys directly, so cost tracking is especially valuable here

Cline / Roo Code

BurnRate reads task-level conversation history from Cline and its forks (Roo Code). Supports three extension IDs.

Data file

api_conversation_history.json per task

Location

VS Code globalStorage/{extensionId}/tasks/{taskId}/

Extension IDs

saoudrizwan.claude-dev, rooveterinaryinc.roo-cline, rooveterinaryinc.roo-code

Features

Full token counts including cache metrics, tool call tracking, per-API-request breakdown

OpenAI Codex CLI

BurnRate reads Codex CLI session logs from the standard sessions directory.

Data directory

~/.codex/sessions/*.jsonl

Features

Input/output tokens, model identification, git branch tracking

Limitation

No cache metrics (Codex doesn't expose them)

Dashboard

The BurnRate dashboard is a single-page web application served locally at http://localhost:8089. It auto-refreshes every 60 seconds and re-fetches data when you switch back to the tab after any absence.

Header Controls

• Provider filter — Filter all data to a single provider (e.g., "Claude Code only")
• Plan selector — Set your subscription plan to calculate value multiplier and savings
• Share button — Generate a shareable JSON snapshot of your usage summary
• PDF export — Download a multi-page PDF report PRO
• Refresh button — Force re-parse all provider data immediately
• License button — Manage your license key and plan

KPI Cards

Five key metric cards at the top of the dashboard, always visible:

Overview Tab

The default view showing a high-level summary of your AI usage:

• Plan Value card — Large display of your value multiplier, API equivalent usage, and total savings
• Daily Token Usage chart — Stacked bar chart showing input (orange), output (yellow), and cache (green) tokens per day
• API Equivalent Cost Trend — Line chart of daily spend at API rates
• Hourly Activity Heatmap — 24-hour grid showing when you're most active
• Model Breakdown — Donut chart of cost distribution across models (Opus, Sonnet, Haiku, etc.)
• Top Sessions — Table of your 5 most expensive sessions
• Agentic vs Interactive — Donut and KPI breakdown showing autonomous agent sessions vs interactive conversations

Sessions Tab

Detailed log of every AI conversation with powerful filtering:

Filter controls:

• Time range presets: 7d, 30d, 90d, All
• Custom date range (from/to)
• Provider, model, project, session type (agentic/interactive/mixed) filters
• Free-text search across session data

Sortable columns: Session ID, Date, Duration, Messages, Input Tokens, Output Tokens, API Equivalent, Cache Hit Rate, Session Type, Agent Count, Project.

Click any row to expand a detailed breakdown showing all session metadata, token counts, tool calls, and project information.

Costs Tab

Comprehensive cost analysis with forecasting:

• Cost summary card — Your plan, API equivalent, savings amount and percentage, value multiplier
• Spend Forecast — Predictive model showing projected monthly/weekly costs, weekday vs weekend averages, trend direction, and per-provider projections
• Daily API Equivalent chart — Bar chart with optional forecast overlay
• Cost by Model — Donut chart of spend per model
• Cost by Project — Horizontal bar chart of top projects by spend
• Cost Projections — Scenario table (current, best case, worst case)
• What-If Analysis — Model provider migration cost calculator

Projects Tab

Usage grouped by project directory:

• Project Spend Breakdown — Horizontal bar chart of top projects by API equivalent cost
• Project Token Trends — Line chart showing token usage over time per project
• Per-Project Tool Usage — Table showing which tools (Read, Write, Bash, etc.) are used most in each project

Usage Tab PRO

Deep analysis of how you use AI tools:

• Billing education — Explains input vs output tokens, caching, and how costs accumulate
• Cost by Operation Type — Bar chart showing spend on file reads, code generation, command execution, etc.
• Tool Usage Frequency — Horizontal bar chart of top 12 tools by call count
• Tool Cost Attribution — Table showing which tools are most expensive
• Avg Tokens per Tool Call — Efficiency metrics per tool
• Redundant Patterns — Detects repeated operations (e.g., reading the same file 50 times)
• Model Recommendations — Per-project suggestions for cheaper models

Optimize Tab PRO

The optimization engine analyzes your usage and generates actionable recommendations. See Optimization Engine for details.

• Optimization Score — 0-100 score showing how well-optimized your usage is
• Savings Banner — Total estimated monthly savings from all recommendations
• Optimization Cards — Filterable by category, provider, and impact level. Each card includes a description, estimated savings, educational content, and auto-apply config snippets
• Plan Advisor — Per-provider plan upgrade/downgrade recommendations
• Context Analysis — Cache hit rate, median/P90/P99 session sizes, session depth breakdown, token accumulation curves, and context bloat detection

Comparison Tab

Side-by-side cost efficiency analysis across all your AI tools:

• Provider metrics table — Cost, sessions, cost/session, cost/message, cost/1K tokens, cache hit rate, output ratio, efficiency score
• Migration calculator — Estimate the cost impact of switching from one provider to another
• Head-to-head mode — Toggle to compare two specific providers in detail

ROI Tab PRO

Return on investment analysis using your git history:

• Total Cost — API equivalent spend
• Cost per Commit — Average cost per git commit
• Lines per Dollar — Lines of code changed per dollar spent
• Commits per Dollar — Productivity metric
• Efficiency Score — Composite 0-100 score
• Files Touched — Total files affected by AI-assisted changes

Limits Tab

Real-time rate limit tracking for providers that expose usage data:

Claude Code limits (via Anthropic OAuth API):

• 5-hour rolling window utilization
• 7-day weekly limit
• 7-day Sonnet-specific limit
• Extra usage (overflow billing for Claude Max)
• Forecast for when each limit will be reached

Cursor activity: Requests today, requests this week, sessions, tokens.

Codex activity: Requests and session counts.

Set custom alert thresholds (e.g., notify at 75% utilization) with the inline controls.

Budgets Tab

Set spending caps per project and receive alerts when approaching limits:

• Budget Status Cards — Visual cards for each configured project showing spend, capacity %, and alert status
• Configure form — Set monthly cap, daily cap, burn rate cap ($/hr), and alert thresholds (default: 75%, 90%, 100%)
• Notifications — Desktop notifications for budget alerts and daily summaries. Test notification button to verify setup.

Agents Tab

Sub-agent observability for Claude Code's Agent tool:

• Agent KPIs — Total agents spawned, cost breakdown, average cost per agent
• Type Breakdown — Count by agent type (Explore, Plan, general-purpose, etc.)
• Top Tools — Most-used tools across all sub-agent sessions
• Session Cost Tree — Hierarchical view of parent sessions and their spawned sub-agents with per-agent costs

Wrapped Tab

Your AI usage highlights in a shareable card format:

• Total AI Spend — Hero stat with personality badge (e.g., "The Optimizer", "The Night Owl")
• Stats — Sessions, messages, providers
• Highlights — Top model, top project, most active hour, cache hit rate
• Share buttons — Twitter, LinkedIn, copy text, download PNG

Optimization Engine PRO

BurnRate's optimization engine includes 46 rules across 7 categories that analyze your usage patterns and generate actionable cost-saving recommendations.

Rule Categories

How It Works

1. BurnRate analyzes your session data against each rule's threshold conditions
2. Triggered rules generate optimization cards ranked by impact (High, Medium, Low)
3. Each card includes: estimated monthly savings, educational explanation, an analogy to make the concept intuitive, and a config snippet you can apply
4. The Auto-Apply feature can automatically patch your config files (e.g., CLAUDE.md, .cursorrules) with the recommended changes

Provider-Specific Examples

• Claude Code: Use effort levels (low/medium/high) for routine tasks, lower autocompact threshold to 50%, create reusable skills, optimize subagent model selection
• Cursor: Use auto mode for generation, create .cursorrules for project conventions, use composer for multi-file edits
• Copilot: Switch to more efficient models, add system instructions to reduce exploration
• Aider: Use efficient edit format, enable prompt caching
• Cline: Use plan-act mode, set max request limits, reduce MCP server overhead

Budget Alerts

Set spending caps per project to prevent runaway costs:

{
  "projectBudgets": {
    "my-project": {
      "monthlyCapUSD": 100,
      "dailyCapUSD": 10,
      "burnRateCapUSD": 5,
      "alertThresholds": [75, 90, 100]
    }
  }
}

• Monthly Cap — Maximum API-equivalent spend per month for this project
• Daily Cap — Maximum daily spend
• Burn Rate Cap — Maximum hourly spend rate (catches runaway sessions)
• Alert Thresholds — Percentage values that trigger notifications (default: 75%, 90%, 100%)

Budget status is shown in the Budgets tab with visual progress bars and color-coded alerts (green = OK, yellow = warning, red = exceeded).

Notifications

BurnRate supports cross-platform desktop notifications:

• macOS — Native notifications via AppleScript
• Linux — notify-send
• Windows — PowerShell MessageBox

Notification types:

• Budget alerts — When project spend crosses alert thresholds
• Daily summary — End-of-day usage recap (5 PM)
• Rate limit warnings — When approaching provider rate limits

A background monitor checks every 5 minutes with deduplication to prevent notification spam.

PDF Reports PRO

Generate a multi-page PDF report of your AI usage analytics. The report includes:

• Cover page with KPI summary cards
• Executive summary
• Cost breakdown by model and provider
• Session analysis and efficiency metrics
• Provider comparison (if using multiple tools)
• Top 10 optimization recommendations
• Trend analysis and forecasting
• Cache efficiency analysis

Click the download button in the dashboard header, or call the API directly:

curl http://localhost:8089/api/export/pdf -o burnrate-report.pdf

Sharing & Snapshots

Generate a shareable summary of your AI usage. The snapshot includes aggregate metrics only — never raw session content, code, or file paths.

• Copy to clipboard — JSON summary for pasting
• Download JSON — Save as file
• Wrapped card — Social-media-ready image with Twitter and LinkedIn share buttons

Rate Limit Tracking

BurnRate tracks real-time rate limit utilization for providers that expose this data:

Claude Code

Reads OAuth credentials from your system keychain and queries the Anthropic usage API for:

• 5-hour rolling window — Short-term burst limit
• 7-day window — Weekly aggregate limit
• Per-model windows — Separate Opus and Sonnet limits
• Extra usage — Overflow billing (Claude Max)

Each window shows utilization percentage, reset countdown, and you can set custom alert thresholds.

Cursor & Codex

Activity-level monitoring (requests and sessions per day/week) — these providers don't expose hard rate limits locally.

Spend Forecasting

BurnRate's forecasting engine predicts your future spending based on historical patterns:

• Projected monthly/weekly cost — Based on recent usage trends
• Weekday vs weekend averages — Accounts for work schedule patterns
• Trend direction — Increasing, decreasing, or stable with percentage change
• Per-provider projections — Individual forecast for each tool
• Budget alerts — Warns if projected spend will exceed configured budgets
• Rate limit forecasting — Predicts when you'll hit usage limits based on velocity

Team Setup TEAM

BurnRate Teams gives engineering leaders visibility into AI spending across their team. Each team member runs the local CLI as usual; aggregated (privacy-safe) metrics are synced to a shared team dashboard.

brew install burnrate-dev/tap/burnrate
burnrate setup

burnrate join <invite-code>

Team Dashboard

The team dashboard at getburnrate.io/team/{id} provides aggregated analytics across all members:

Team KPIs

• Total Cost — Combined API-equivalent spend across all members
• Total Sessions — Aggregate session count
• Members — Active team member count
• Busiest Day — Day with highest collective spend

Team Tabs

• Overview — High-level KPIs and cost visualization
• Members — Per-member table with cost, sessions, last sync. Click to expand detail. Invite new members inline.
• Analytics — Cost time-series charts with 7d/30d/90d range, provider and model breakdown charts
• Budgets — Team-wide and per-project budget caps with alert configuration
• Optimizations — Team-wide cost-saving recommendations based on aggregated patterns

Inviting Members

Team admins can invite members in two ways:

1. Email invite — Enter the member's email in the Members tab. They receive an email with a join link.
2. Invite link — Generate a shareable invite link. Anyone with the link can join the team (subject to max uses if configured).

Members join by visiting the link or using the CLI:

burnrate join abc123def456

Privacy & Data

What IS synced:

• Total sessions, messages, and token counts
• Estimated cost and projected monthly cost
• Project names (not file paths or directories)
• Model usage breakdown
• Tool usage frequency
• Efficiency metrics (cache hit rate, session depth, output ratio)

What is NEVER synced:

• Source code or file contents
• Session transcripts or message text
• File paths or directory structures
• Git branch names or commit content
• Personal configuration

The device identifier is a SHA-256 hash of your hostname and home directory — it cannot be reversed to identify you.

Plan Comparison

License Keys

License keys unlock Pro or Team features on the local CLI. Each key is a 64-character hex string prefixed with tt_.

Activating a Key

Three ways to activate:

1. Setup wizard: burnrate setup and enter when prompted
2. Dashboard: Click the shield icon in the header and enter in the License modal
3. Config file: Add "licenseKey": "tt_your_key_here" to ~/.burnrate/config.json
4. Environment variable: BURNRATE_LICENSE=tt_your_key_here burnrate

Validation

• Keys are validated against the BurnRate cloud API every 24 hours
• A 7-day offline grace period lets you use BurnRate without internet
• Keys can be revoked from the cloud dashboard

Billing & Checkout

Billing is handled through Stripe. From the cloud dashboard at getburnrate.io/app:

• Subscribe — Choose Pro or Team plan at checkout
• Manage — Access the Stripe customer portal to update payment, view invoices, or cancel
• Referrals — Share your referral link for 20% off for 3 months (for the referee)

CLI Commands

Config File Reference

Full configuration reference for ~/.burnrate/config.json:

{
  "licenseKey": "tt_abc123...",
  "licenseServer": "https://getburnrate.io",
  "port": 8089,
  "plan": "max20x",
  "planCost": 240,
  "providers": "auto",
  "providerPlans": {
    "cursor": "cursor-pro",
    "copilot": "copilot-business"
  },
  "teamSync": true,
  "teamCode": "abc123def456",
  "projectBudgets": {
    "my-app": {
      "monthlyCapUSD": 150,
      "dailyCapUSD": 15,
      "burnRateCapUSD": 5,
      "alertThresholds": [75, 90, 100]
    }
  },
  "notifications": {
    "enabled": true,
    "budgetAlerts": true,
    "optimizationAlerts": false,
    "dailySummary": true
  }
}

Model Pricing

BurnRate calculates API-equivalent costs using current model pricing (per million tokens):

Anthropic (Claude)

OpenAI

Google

Environment Variables

Troubleshooting

No data showing up

• Verify you have at least one supported AI tool installed and have used it recently
• Run burnrate config to check which providers are configured
• Check that the data directories exist (see Supported Providers for paths)
• Click the Refresh button in the dashboard header to force a re-parse
• For Cursor: ensure the SQLite database exists at ~/.cursor/ai-tracking/ai-code-tracking.db

Dashboard goes blank after being idle

If the browser tab has been in the background for an extended period (e.g., overnight), the auto-refresh timer may have been throttled by the browser. Simply click anywhere on the page or switch to the tab — BurnRate automatically re-fetches data when the tab becomes visible.

Rate limits not showing

• Claude Code limits require OAuth credentials stored in your system keychain. On macOS, these are read automatically. On other platforms, you may need to provide the token manually.
• Cursor and Codex don't expose hard rate limits — BurnRate shows activity metrics instead.

License key not activating

• Ensure the key starts with tt_ and is the full 64+ character string
• Check your internet connection — keys are validated against the BurnRate cloud API
• Try setting via environment variable: BURNRATE_LICENSE=tt_... burnrate
• Previously activated keys work offline for 7 days (grace period)

High memory usage

If you have thousands of sessions, BurnRate's initial parse may use more memory. It parses files in parallel using a worker pool. After the initial parse, data is cached for 5 minutes before the next refresh.

Port already in use

If port 8089 is occupied, set a different port:

# Via environment variable
PORT=8090 burnrate

# Or in config file
# Set "port": 8090 in ~/.burnrate/config.json

Getting help

If you're still stuck:

• File an issue on GitHub
• Use the live chat widget on getburnrate.io
• Email matt@getburnrate.io