codeburn

Automatically locates and parses session logs from Claude Code, Cursor, GitHub Copilot, Codex, and other AI coding tools by scanning platform-specific directories (~/.claude, ~/.config, etc.). Implements a provider plugin system with standardized parsers that convert heterogeneous log formats into a unified ParsedTurn and Session object model, enabling downstream analysis across multiple tools without manual configuration.

Analyzes parsed session turns and classifies them into TaskCategory buckets (coding, testing, terminal usage, debugging, etc.) using heuristic rules based on turn content, tool invocations, and file types. Implements a classifyTurn function that examines API calls, file modifications, and context patterns to assign semantic meaning to raw token consumption, enabling cost breakdown by activity type rather than just by model.

Provides CLI commands (codeburn status, codeburn report) that generate detailed reports on session discovery status, parsing errors, and data quality metrics. Implements metadata inspection capabilities that allow developers to examine individual session files, view parsing errors, and understand data completeness. Generates status summaries showing how many sessions were discovered, parsed successfully, and skipped due to errors.

Implements a plugin-based architecture that allows new AI coding providers to be added without modifying core CodeBurn code. Each provider plugin implements standardized interfaces (discoverAllSessions, parseSessionFile) that return normalized ParsedTurn and Session objects. Plugins are loaded dynamically at runtime and can be distributed as npm packages, enabling community contributions and custom provider support.

Calculates USD costs for each turn by multiplying token counts (input + output) by model-specific pricing rates sourced from LiteLLM's pricing database, which covers 100+ models across OpenAI, Anthropic, and other providers. Implements a calculateCost function that handles variable pricing tiers, currency conversion, and subscription plan adjustments (e.g., Claude Pro discounts), ensuring accurate financial visibility without requiring API calls to pricing services.

Renders a terminal-based interactive dashboard (TUI) using a framework like Ink or Blessed that displays aggregated token usage, costs, and efficiency metrics across multiple time periods (Today, 7 Days, 30 Days, All Time). Implements keyboard-driven navigation, filtering by project/model/task category, and drill-down capabilities that allow developers to explore cost patterns without leaving the terminal. Updates metrics in real-time as new session data is discovered.

Aggregates parsed session turns into daily buckets and higher-level time periods (7 Days, 30 Days, All Time) using an aggregateProjectsIntoDays function that groups by date, project, and model. Implements a caching layer that stores aggregated results to avoid recomputing statistics on every dashboard load, with cache invalidation triggered by new session data discovery. Supports efficient querying of cost trends across arbitrary time windows.

Scans session history to identify inefficient token usage patterns such as redundant file reads, bloated context windows, unused MCP tool invocations, and low one-shot success rates. Implements an optimization engine (codeburn optimize) that analyzes turn sequences, detects repeated operations on the same files, and generates actionable recommendations to reduce token waste. Uses heuristic rules and statistical analysis to flag anomalies in token consumption.

Implements a model comparison engine (codeburn compare) that analyzes token usage and costs across different AI models used in the same session history, calculating metrics like cost-per-successful-turn, average context size, and one-shot success rate per model. Generates comparison matrices and visualizations that help developers understand which models are most cost-effective for their specific workflow, accounting for both raw cost and task completion efficiency.

Exports aggregated cost data and detailed turn records to CSV and JSON formats with support for custom filtering by project, model, task category, date range, and other dimensions. Implements an exportCsv function that generates spreadsheet-compatible output suitable for further analysis in Excel, Google Sheets, or data analysis tools. Supports both summary-level exports (daily aggregates) and detailed exports (individual turns with full metadata).

Provides a native macOS menubar application that displays real-time token usage and cost metrics in the system menu bar, with a dropdown menu showing today's spend, weekly trends, and quick access to the full dashboard. Implements app lifecycle management, state persistence, and background monitoring that updates metrics as new session data is discovered. Uses native macOS UI frameworks for seamless integration with the operating system.

Manages subscription plan settings (free, Claude Pro, enterprise) and currency preferences (USD, EUR, GBP, etc.) that affect cost calculations and display. Implements a configuration system that stores user preferences persistently and applies subscription-specific discounts (e.g., Claude Pro 20% reduction) and currency conversion to all cost metrics. Supports multi-currency display for international teams.