CodeBurn Documentation

CodeBurn Desktop is a local-first Electron application that acts as a view layer for the codeburn CLI. It does not re-implement analytics; instead, it spawns the CLI to fetch and render JSON data.

Key Architectural Components:

• Main Process: Handles the codeburn binary resolution, spawns CLI processes with --json flags, manages a 30s polling timer, and handles IPC.
• Preload Script: Exposes a minimal, typed window.codeburn surface via contextBridge to the renderer.
• Renderer Process: A React 19 application that runs with contextIsolation: true and nodeIntegration: false. It consumes data via IPC and renders the six main sections.
• Data Flow: The app uses the 'menubar pattern' where the CLI is invoked per section (e.g., codeburn status --format menubar-json), the JSON is decoded, and the renderer displays it.

The CodeBurn MCP (Model Context Protocol) server is a stdio server that exposes CodeBurn's usage and cost data to AI agents. It provides two primary tools:

1. get_usage: Returns usage and cost data.
2. get_savings: Returns savings data.

Both tools return data in two formats: a markdown table for human readability and typed structured JSON for programmatic use by the agent. The server uses a long-lived in-process McpServer that coalesces concurrent calls and relies on a 180s parser cache for performance.

CodeBurn uses a provider-based system to integrate with various AI coding tools and agents. Providers are categorized by their loading behavior:

• Eager Providers: Always loaded by the system. These typically read from local files like JSON, JSONL, or SQLite databases (e.g., Claude, Copilot, Gemini).
• Lazy Providers: Loaded only on their first call. These may use different communication methods like protobuf over RPC or REST API (e.g., Antigravity, Vercel AI Gateway).

If you are developing for a specific provider, you should locate its source file in src/providers/ and its corresponding test file in tests/providers/ to understand its specific data source and edge cases.

The codeburn sync process operates by reading local configuration and credentials to push telemetry data to a remote backend.

Local Files:

• Configuration: ~/.config/codeburn/sync.json (contains baseUrl, clientId, issuer, tracesPath)
• Credentials: ~/.config/codeburn/.sync-token (managed via OS credential store)
• Sent Ledger: ~/.cache/codeburn/sync-ledger.json (tracks sent calls for deduplication)

Push Workflow:

1. Read config and refresh token.
2. Authenticate via OIDC to get an access_token.
3. Collect calls and filter against the sent-ledger to ensure only unsent calls are processed.
4. Build an OTLP/HTTP JSON payload.
5. POST the payload to {baseUrl}{tracesPath} using the Bearer token.
6. On success, update the ledger and lastSync in config.

CodeBurn can automatically ingest task usage and conversation data from the Cline VS Code extension. It scans two specific locations for task data:

1. VS Code globalStorage: The directory for saoudrizwan.claude-dev.
2. Cline home-data: The directory at ~/.cline/data.

For a task to be discovered and included, the directory must contain a tasks/ child directory and include a ui_messages.json file. The provider uses ui_messages.json for api_req_started usage entries and api_conversation_history.json for model extraction.

If a release contains broken assets (like a corrupted menubar zip), you can overwrite them without creating a new tag using the GitHub CLI --clobber flag. This ensures users running the installer pick up the fixed files automatically.

gh release upload mac-v0.9.8 mac/.build/dist/CodeBurnMenubar-v0.9.8.zip --clobber
gh release upload mac-v0.9.8 mac/.build/dist/CodeBurnMenubar-v0.9.8.zip.sha256 --clobber

IBM Bob stores its IDE task history in the application data directory under User/globalStorage/ibm.bob-code/tasks/. CodeBurn checks the following default paths based on your platform:

Note: The Bob-IDE paths are included to support older installations that used the preview-era application name.

By default, the provider scans known Kimi Code runtime stores. You can narrow the scan to a specific directory by setting the KIMI_CODE_HOME environment variable.

Default scan locations:

• ~/.kimi-code
• ~/Library/Application Support/kimi-desktop/daimon-share/daimon/runtime/kimi-code/home (Kimi desktop / IDE embedded runtime)

Internal directory structure scanned: Inside each home, the provider looks for sessions in: $HOME/sessions/wd_*/<session-dir>/ (CLI) or conv-* / ctitle-* (embedded runtimes).

Each session directory must contain:

• state.json
• agents/<agent-id>/wire.jsonl

To begin syncing your AI usage telemetry to a shared backend, perform a one-time setup followed by pushing your data and checking the status.

1. Setup: Run codeburn sync setup <url> to configure your endpoint and log in via your browser.
2. Push: Run codeburn sync push to send recent usage data.
3. Status: Run codeburn sync status to verify your configuration and authentication state.

# One-time setup (opens browser for login)
codeburn sync setup https://metrics.your-team.com

# Push recent usage
codeburn sync push

# Check status
codeburn sync status