codeburn/docs/design/codeburn-desktop.md

# CodeBurn Desktop — Design Spec

**Date:** 2026-07-10
**Branch:** `feat/desktop-app` (cut from `origin/main`, v0.9.15)
**Design reference:** `codeburn-desktop-wireframes.html` (v6.1 "indigo instrument", repo root)
**Status:** Approved design → implementation planning

---

## 1. Summary

Build **CodeBurn Desktop** — a standalone, resizable native desktop application (Electron) that
renders the approved v6 "indigo instrument" wireframes. It is a first-class app in the vein of
Claude Desktop / the Codex app, **distinct from**:

- the `dash/` **web dashboard** (React app served by `codeburn web`) — untouched, unrelated;
- the `mac/` + `gnome/` **menubar** apps — small tray popovers.

The desktop app is local-first: it never sends data anywhere, and it does **not** re-implement
usage analytics. All aggregation stays in the `codeburn` CLI; the app is a view layer that spawns
the CLI and renders its JSON — the same contract the menubar apps use today.

## 2. Goals / Non-goals

**Goals**
- A resizable window with six sections: **Overview · Spend · Optimize · Models · Plans · Settings/Devices**.
- Pixel-faithful to the approved wireframe (the wireframe CSS is the design system, ported verbatim).
- Data via the **menubar contract**: spawn `codeburn … --json`, decode, poll on a 30s timer + on demand.
- Reuse existing CLI JSON where it exists; add small new `--json` emitters where the wireframe needs
  data that the CLI doesn't expose yet. **No faked/stubbed data in the renderer.**

**Non-goals (this milestone)**
- Signed/notarized distributable (`.dmg`/`.app`/installer). Milestone 1 runs locally (`electron .`);
  packaging (electron-builder + notarization) is an explicit follow-up.
- Touching `dash/`, `mac/`, `gnome/`, or the existing Tauri popover.
- Auto-update, telemetry, cloud sync, multi-window.

## 3. Architecture

New top-level directory `app/` in the monorepo:

```
app/
├── package.json              # own package: electron, vite, react 19, typescript
├── electron/
│   ├── main.ts               # BrowserWindow lifecycle, 30s poll timer, IPC handlers
│   ├── cli.ts                # resolve codeburn binary path + spawn `codeburn … --json` (argv, no shell)
│   └── preload.ts            # contextBridge → window.codeburn.{getOverview,getModels,getPlans,getDevices,…}
├── renderer/
│   ├── index.html
│   ├── main.tsx
│   ├── App.tsx               # sidebar nav + window chrome (period/provider), section router (local state)
│   ├── styles/
│   │   └── indigo.css        # wireframe CSS ported verbatim (tokens + component classes)
│   ├── sections/
│   │   ├── Overview.tsx  Spend.tsx  Optimize.tsx  Models.tsx  Plans.tsx  Settings.tsx
│   ├── components/           # shared: Window chrome, Panel, StatCard, CapsuleChart, StackedBars,
│   │                         #         Sankey, ListRow, Track, SegTabs, etc. (extracted from wireframe)
│   ├── lib/
│   │   ├── ipc.ts            # typed wrappers over window.codeburn.*
│   │   └── types.ts          # TS types mirroring each CLI JSON payload
│   └── hooks/                # useOverview(period), useModels(), … (poll + cache)
└── vite.config.ts
```

**Process model**
- **Main process** is the only place that touches the CLI or the filesystem. It:
  - resolves the `codeburn` binary path (persisted-path file → `PATH` fallback across brew/nvm/volta/asdf,
    mirroring `mac/Sources/CodeBurnMenubar/Security/CodeburnCLI.swift`);
  - spawns `codeburn <subcommand> --json …` as plain argv (no shell), with a hard timeout (~45s) and a
    cap on concurrent spawns;
  - exposes IPC handlers per data need; re-polls every 30s and on user action (period/provider change,
    manual refresh);
  - handles the "CLI not found / non-zero exit / bad JSON" states → surfaces the wireframe's empty /
    permission-denied states (§7 "States & trust").
- **Renderer** runs with `contextIsolation: true`, `nodeIntegration: false`. It receives typed data over
  IPC and renders. No Node, no direct spawn.
- **preload** exposes a minimal, typed `window.codeburn` surface via `contextBridge`.

**Binary resolution** reuses the menubar approach; if `codeburn` cannot be found, the app shows a
first-run "point me at your codeburn CLI" state rather than crashing.

## 4. Data contract (the menubar pattern, generalized)

The app spawns the CLI per section and decodes JSON. Aggregation is 100% CLI-side.

| Section | CLI invocation | Payload | Exists today? |
|---|---|---|---|
| Overview | `codeburn status --format menubar-json --period 30days [--provider X]` | `MenubarPayload` (`src/menubar-json.ts`) | ✅ |
| Spend (bars, projects) | same `MenubarPayload` (`current.topProjects`, `history.daily`) | — | ✅ (⚠ per-model-per-day may need `history.daily` enrichment) |
| Spend (Sankey model→project) | **new** `codeburn spend --format flow-json` (or extend menubar payload) | model×project cost matrix | ⚠ **new emitter** |
| Optimize (waste) | `MenubarPayload.optimize` | findings | ✅ |
| Optimize (reverts/abandoned) | **new** `codeburn yield --json` | shipped-vs-reverted, abandoned sessions | ⚠ **new emitter** |
| Models | `codeburn models --json` | per-model table (calls/input/output/cache/cost/saved) | ✅ |
| Plans | **new** `codeburn plan --json` (list plans + usage vs cycle) | plans + progress | ⚠ **new emitter** (data exists in `src/config.ts`; needs JSON shape) |
| Settings/Devices | `codeburn devices --json` / `codeburn share status --json` (or the `origin/main` `/api/devices`,`/api/share/status` handlers as reference) | this device, discovered, paired | ✅ commands exist on main; ⚠ confirm/​add `--json` |

**Rule:** every ⚠ becomes its own CLI-side task in `src/` (TypeScript). The renderer never invents data;
if an emitter isn't ready, its section shows the wireframe's honest loading/empty state, not fake numbers.

`renderer/lib/types.ts` mirrors each payload as a hand-kept TS type (same convention `dash/` uses — no
shared type package). Where a menubar payload type already exists in `src/menubar-json.ts`, copy it.

## 5. Styling

Port the wireframe's hand-written CSS **verbatim** into `renderer/styles/indigo.css`:
- token block (`--pg / --panel / --blue / --purple / --lav / --cyan / --grad / --grad-bar / …`);
- component classes (`.win / .sb / .ni / .bar / .panel / .phead / .stat / .plot / .bars / .sbars /
  .li / .track / .seg / .pop / .btn / .rail / .mini / …`).

Each wireframe section (`<section>` blocks in the HTML) maps near-directly to a React component. Shared
repeating structures (`.panel`, `.stat`, capsule chart, stacked bars, the Sankey SVG, list rows, plan
tracks) get extracted into `renderer/components/` so the six sections compose them rather than duplicate
markup. This keeps the approved look exactly while giving each section a clean, independently-testable
boundary. **Not** rebuilding in Tailwind — that would risk drift from the approved design and cost time.

Light theme is a follow-up (wireframe notes a light ladder using the same tokens); ship dark first.

## 6. Section specs (what each renders)

1. **Overview** — 4 stat cards (Today, Month-to-date, Projected month, Waste found), the daily-spend
   capsule chart (30 bars, gradient+glow on peak), "Most expensive sessions" list. Source: `MenubarPayload`
   (`current`, `history.daily`, `topSessions`, `optimize.savingsUSD`); projected month computed from history.
2. **Spend** — lens tabs (Projects/Activity/Tools/MCP/Subagents); stacked daily-by-model bars + "By project"
   list; the **model→project Sankey** signature. Sankey needs the new flow emitter.
3. **Optimize** — segment tabs (Waste / Reverts / Abandoned / Fixes) with dollar totals; ranked findings with
   evidence (mono) + copy-fix chips. Waste from `optimize`; reverts/abandoned from new `yield --json`.
4. **Models** — pricing table with per-model series dots (calls/input/output/cache/cost/saved), unpriced-row
   "add alias" affordance, Compare mode. Source `models --json`.
5. **Plans** — vendor-cycle plan tracks (gradient fill; red past 100%), pace warnings as text. Source new
   `plan --json`.
6. **Settings/Devices** — settings rail (General/Providers/Aliases/Plans/Devices/Export/Privacy); Devices pane:
   this device, discovered-nearby (approve), paired list, "combine usage" toggle. Source devices/share JSON.
7. **States & trust** (cross-cutting) — per-provider empty/permission-denied/loading/provenance states, wired
   from CLI exit codes + partial payloads.

Window chrome (traffic lights, app mark, sidebar nav with ⌘1–⌘5 / ⌘,, period segmented control, provider
popover, ⌘K affordance, footer hints) is shared across all sections.

## 7. Task decomposition (for delegated implementation)

Fable orchestrates and reviews; implementers are **Opus 4.8 (primary)** and **Codex 5.6-high (alternate)**.

- **T0 — Scaffold** (`app/` Electron+Vite+React, main/preload/renderer, IPC bridge, `indigo.css` port,
  shared `components/`, window chrome + sidebar nav, `codeburn` path resolution + one working IPC call).
  → Opus 4.8. **Blocks all section work.**
- **T1 — CLI JSON emitters** in `src/` (TypeScript): `spend … flow-json` (Sankey matrix), `yield --json`,
  `plan --json`, confirm/add `devices/share … --json`; unit tests in `tests/`. → Codex 5.6-high. Parallel with T0.
- **T2 Overview**, **T3 Spend**, **T4 Optimize**, **T5 Models**, **T6 Plans**, **T7 Settings/Devices** — one
  self-contained component + typed hook each. Split across Opus 4.8 + Codex 5.6-high. Each depends on T0;
  T3/T4/T6/T7 also depend on their T1 emitter (mock the typed payload until the emitter lands, then swap).
- **T8 — Integration pass**: 30s polling, refresh-on-action, error/empty/loading states end-to-end,
  README + `npm run app:dev`. → Opus 4.8.

Every returned unit comes back to Fable for review before it counts as done.

## 8. Milestones

- **M1 (this effort):** app runs via `electron .` (dev), all six sections rendering real CLI data (⚠ gaps
  filled by T1 emitters), dark theme, honest states. No packaging.
- **M2 (follow-up):** electron-builder packaging, code-sign + notarize, `codeburn app` launcher subcommand
  (mirroring `codeburn menubar`), auto-update, light theme.

## 9. Testing / verification

- **CLI emitters (T1):** vitest in `tests/` against fixtures (the repo's established pattern).
- **Renderer:** component render tests for each section against typed mock payloads (Vitest + RTL; add to
  `app/`). Typecheck via `tsc --noEmit`.
- **End-to-end smoke:** launch `electron .` against real local session data; verify each section populates,
  period/provider switching re-polls, and CLI-missing → first-run state. Verified by Fable before sign-off.

## 10. Risks / open items

- **Data-shape drift:** hand-kept types between `src/` and `app/` can diverge (same risk `dash/` carries).
  Mitigation: copy menubar types verbatim; T1 emitters ship with typed fixtures the renderer reuses.
- **Sankey matrix cost:** model×project aggregation may be non-trivial in `usage-aggregator.ts`; if it slips,
  Spend ships bars+projects first and the Sankey lands in a fast follow.
- **Provider-name / project-path privacy:** local app shows real project names (unlike shared/sanitized data);
  fine for a local-only window, but keep the sanitize boundary in mind for any future device-pull views.
- **Electron version / security defaults:** pin Electron, enable `contextIsolation`, disable `nodeIntegration`,
  restrict `preload` surface; no remote content loaded.
```