codeburn/docs
Resham Joshi a88dffe7aa
fix(export): give the JSON export stable keys (#1864)
* fix(export): give the JSON export stable keys

The JSON export reused the CSV row builders, so its keys were display
headers with spaces and parentheses, and the money keys changed name
with the configured currency. A program had to reshape the file before
it could read it.

The builders now produce one camelCase row, and a single key to header
map writes the CSV, so every CSV header line stays byte-identical. The
JSON schema moves to codeburn.export.v3; the currency is stated once in
currency.code and the money values stay converted to it.

Before (v2, EUR):
{"Period":"7 Days","Date":"2026-11-02","Cost (EUR)":1.1,"Saved (EUR)":0,"API Calls":1,"Sessions":1,"Input Tokens":100000,"Output Tokens":50000,"Cache Read Tokens":200000,"Cache Write Tokens":30000,"costBasis":{"calculated":1}}

After (v3, EUR):
{"period":"7 Days","date":"2026-11-02","cost":1.1,"saved":0,"apiCalls":1,"sessions":1,"inputTokens":100000,"outputTokens":50000,"cacheReadTokens":200000,"cacheWriteTokens":30000,"costBasis":{"calculated":1}}

v2 consumers must rename keys. New keys can still appear under v3.

* docs: changelog entry for the v3 export JSON

* test: read the v3 export keys
2026-11-05 00:49:36 +01:00
..
design feat(dock): one Claude ring per config directory, with its own sessions and today (#1570) 2026-09-28 19:06:53 +02:00
providers chore: drop the no-zstd fallbacks the 22.15 floor made unreachable (#1855) 2026-11-04 19:29:18 +01:00
release-acceptance test(perf): add Phase 0 wait-path harness and pin main baselines 2026-08-29 23:45:46 +05:30
sync feat(sync): additive CB-3 usage-span fields and coverage watermark (Teams boundary spec section 7) (#1135, #1140) (#1147) 2026-08-25 11:32:45 -07:00
architecture.md feat(providers): add Command Code (#1658) 2026-10-07 00:18:50 +02:00
by-branch.md Add spend-by-branch report (spend --format branch-json) 2026-09-12 13:09:00 -07:00
cli.md fix(export): give the JSON export stable keys (#1864) 2026-11-05 00:49:36 +01:00
compare-cohorts.md Wire cohort samples to the real drill-through, scope and serve the new flags 2026-09-12 14:02:01 -07:00
compare-periods.md Compare periods: lead sentence, three tiles, day bars, top movers (#1446) 2026-09-15 23:12:12 +02:00
configuration.md README: tell the story first, keep the manual in docs (#1527) 2026-09-22 16:28:27 +02:00
drill-through.md Fix drill-through provider, day and model attribution 2026-09-12 12:22:19 -07:00
guard.md feat(guard): warn and stop identical-call loops and failing-command retries (#1857) 2026-11-04 19:29:23 +01:00
how-it-works.md chore: drop the no-zstd fallbacks the 22.15 floor made unreachable (#1855) 2026-11-04 19:29:18 +01:00
mcp.md feat(export): say where every dollar comes from (#1863) 2026-11-05 00:10:27 +01:00
menubar.md feat(dock): one Claude ring per config directory, with its own sessions and today (#1570) 2026-09-28 19:06:53 +02:00
optimize.md feat(optimize): flag one-hour cache writes the next request never needed (#1860) 2026-11-05 00:10:23 +01:00
plans-and-quota.md feat: Google AI plan presets and the Antigravity tier label (#1683) 2026-10-07 23:34:49 +02:00
README.md feat: CodeBurn for VS Code (#1670) 2026-10-07 16:46:23 +02:00
vscode.md chore: raise the Node floor to 22.15 and make zstd unconditional (#1846) 2026-11-04 17:37:28 +01:00
web.md feat(web): --allowed-host for an authenticating reverse proxy (#1789) 2026-11-02 17:17:06 +01:00
yield.md README: tell the story first, keep the manual in docs (#1527) 2026-09-22 16:28:27 +02:00

Docs index

One line per file in this directory, recursively.

docs/

  • architecture.md — A map of the codebase.
  • by-branch.md — The Spend view in CodeBurn Desktop has a By branch panel: pick a project and see where its AI spend went, per git branch, with the recorded worktrees and the individual sessions behind each branch.
  • cli.md — Every CodeBurn command and keyboard shortcut, plus the report-focused flags for filtering, JSON output, and diagnosing detection.
  • compare-cohorts.md — The classic Compare view answers "how do these two models differ across my whole history?" by aggregating everything each model ever did.
  • compare-periods.md — Compare two date ranges side by side and see exactly what drove the change in usage and cost.
  • configuration.md — Currency, model aliases, local/custom-priced/proxy models, and environment variables.
  • drill-through.md — CodeBurn Desktop can open any aggregate as a session list that explains exactly what composes it, without losing your place.
  • guard.md — Opt-in Claude Code hooks that watch session cost while you work: soft cap, hard cap, checkpoint nudge, session openers.
  • how-it-works.md — Pricing, task categories, breakdowns, one-shot rate, per-tool data locations and parsing, and how to read the dashboard.
  • mcp.md — codeburn mcp runs a local MCP server over stdio so an AI agent can ask about your usage and savings mid-conversation.
  • menubar.md — The macOS menu bar app, Windows tray app (with WSL discovery), and Linux GNOME Shell extension.
  • optimize.md — codeburn optimize scans your Claude Code sessions and your ~/.claude/ setup, reports what is costing tokens without earning them, and grades the setup A to F.
  • plans-and-quota.md — Subscription plan tracking and live provider quota via codeburn quota.
  • vscode.md — The VS Code extension: how it reuses the CLI client and the desktop renderer, which Node it runs on, workspace scope, and how to build and test it.
  • web.md — The local browser dashboard and combining usage across your paired devices.
  • yield.md — codeburn yield correlates AI sessions with git commits to show what actually shipped.

docs/design/

  • design/capacity-dock.md — Status: implementation specification (Epic: Quota Intelligence #725).
  • design/codeburn-desktop-plan.md — Goal: a standalone Electron desktop app that renders the approved v6 "indigo instrument" wireframes, fed entirely by spawning the codeburn CLI for JSON.
  • design/codeburn-desktop.md — Build CodeBurn Desktop, a standalone, resizable native desktop application (Electron) that renders the approved v6 "indigo instrument" wireframes.
  • design/codeburn-mcp-plan.md — Goal: add a codeburn mcp stdio MCP server exposing CodeBurn's usage/cost data to AI agents via two tools (get_usage, get_savings).
  • design/codeburn-mcp.md — CodeBurn already aggregates rich AI-coding usage/cost data (by task, model, project, provider; retry tax; routing waste; optimize findings; 365-day history).
  • design/desktop-data-lifecycle.md — Status: implementation contract for the quality/performance epic.
  • design/perf-cache-fix.md — codeburn status --format menubar-json was measured taking 25-90+ seconds per call, with no speedup on a repeat call against an unchanged, freshly-warmed cache.

docs/providers/

docs/release-acceptance/

docs/sync/

  • sync/README.md — Push your AI usage telemetry to a shared backend so teams can track adoption, budgets, and ROI across developers.
  • sync/DEVELOPER.md — Architecture, protocol, server contract, and testing for codeburn sync.