helder/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project state

This is a **greenfield project**. No application code, build setup, or `package.json` exists yet — only a design handoff. The first real task is to scaffold the Electron app and port the prototype. Until then, treat the two handoff documents as the contract:

- **`DESIGN.md`** — functional/UX source of truth. Every panel, interaction, state, and edge case at the behavior level. Read this for *what the app does*.
- **`design_handoff_helder_workbench/README.md`** — technical source of truth. Structure, design tokens, recommended stack, real-integration mechanics, and the suggested implementation order. Read this for *how to build it*.

The prototype in `design_handoff_helder_workbench/design/` (React 18 + Babel from CDN, all mock data) is a **visual/interaction reference only — do not ship it as-is**. The HTML is canonical for look and feel; `design/styles.css`'s `:root` block is the canonical design-token list. The `design/src/*.jsx` files map directly to the components to build, but their mock data (`data.js`) and simulated terminals/agent must be replaced with real integrations.

## What Helder is

A dark-only (no light mode, no theme toggle) Electron desktop code workbench for reviewing code written by an AI agent. One project per window. Four resizable columns left→right: **Source Control (git)**, **Explorer (file tree)**, **Editor (tabs + diff)**, **Right column (Claude agent terminal stacked over a shell terminal)**. Plus a top title bar and bottom status bar. The defining feature is the **Copy reference / Pass on to Agent** flow that pushes `path:line` references into the agent's input.

## Recommended stack (no codebase exists — follow README)

- Electron (latest stable), main + renderer + preload bridge with `contextIsolation: true`.
- Renderer: React 18 + TypeScript + Vite (`electron-vite` scaffold). Prototype is already React, so component structure ports directly.
- Syntax highlighting: Prism 1.29 (or swap to Shiki/CodeMirror 6; token→color mapping is documented in README).
- Fonts: UI = system stack; code/mono = **JetBrains Mono bundled locally** (never Google Fonts CDN in Electron).

## Architecture rules and gotchas (these will bite if ignored)

- **Renderer never touches the filesystem, git, or PTYs directly.** All FS (`fs` + `chokidar`), git (`git` / `simple-git`), search (`rg` + fuzzy), terminals (`node-pty` + `xterm.js`), and clipboard go through the main process via IPC / the preload bridge. The prototype keeps all state in the top `App` component; in the real app, lift FS/git/terminal state into main and stream over IPC.
- **Prism PHP load order:** `prism-php` requires `prism-markup-templating` to be loaded **first**, or every `Prism.highlight` call throws and silently falls back to plain text.
- **Pass on to Agent uses bracketed paste.** Write inserts to the agent PTY wrapped in `\x1b[200~ … \x1b[201~` so the `claude` CLI treats it as *pasted, unsubmitted* input. Insert must never submit — it lands as a new line so the user can stack several references before sending.
- **The four diff view modes (Original / Updated / Diff / Split) all derive from one original-text + updated-text pair per changed file.** The prototype computes this with an LCS line diff (`buildDiff()` in `design/src/data.js`); production should prefer real `git diff` output but keep the same four derived views and the same color language everywhere: **red = removed/changed-from, green = added/changed-to**, syntax highlighting on in all modes.
- **The agent pane is just a terminal running the `claude` CLI** (`ai.command`, default `claude`, auto-launched when `ai.autoLaunch` is on). The bottom pane is a normal shell PTY. The prototype's simulated agent session (`agentSeed`, `runAgent`, `bootAgent` in `terminals.jsx`) exists only to show the visual style — keep the styling, drop the fakery.
- **Chrome budget:** title bar + tab strip + panel headers + status bar combined should stay ≈10% of vertical height. Keep it minimal.

## Confirmed decisions (the "Open assumptions" in DESIGN.md are resolved — do not re-ask)

- Search overlay layout: **content matches left (70%), file-name matches right (30%)** — keep as designed.
- Tabs **show an unsaved indicator** (a dot in place of the close control) because auto-save defaults off (`editor.autoSave`).
- Explorer right-click offers a **file-level Copy reference** (project-relative path only), consistent with the editor's Copy reference — in scope.

## Scope boundaries (this version)

- **Git covers staging, unstaging, committing, and discarding only.** Push, pull, fetch, and branch switching are explicitly out of scope. The branch summary bar and status bar are display-only.
- **One agent terminal and one shell terminal** — no additional tabs or sessions.
- The breadcrumb and status-bar items are **display only** (not clickable, do not navigate).
- **Discard is the only destructive git action** and must confirm first (`git.confirmDiscard`, default on). Staging/unstaging do not confirm by default.

## Configuration

Settings are project-scoped, living in a `.helder/` folder in the opened project's root:

- `.helder/config.json` — sparse; only user-overridden values.
- `.helder/config.default.json` — full defaults, **regenerated on launch** from built-in defaults (live documentation of every setting; the app never reads user edits from it).
- Effective value = `config.json` if present, else `config.default.json`, merged key by key.
- `.helder/theme.css` — custom CSS theme applied over the built-in dark theme; **code font and font size live here**, not in the config files.

## Design tokens

Canonical source is the `:root` block in `design_handoff_helder_workbench/design/styles.css`. Surfaces are cool charcoal (`--bg-0` editor `#16171a` → `--bg-3` headers/tabs `#23262b`); single cool-blue accent `--accent #4d8dff`; git status `--add #5cbd6b` / `--del #e0696a` / `--mod #d8a85c` / `--ren #5aa6d6`. File-type icons are 15×15 monogram chips (no brand logos). Recreate UI icons as a small inline-SVG set (or Lucide), keeping the monogram chips for file types. Respect `prefers-reduced-motion`; keep motion subtle.

## Suggested implementation order (from README)

1. Electron shell + frameless dark window; port tokens to CSS vars; bundle JetBrains Mono.
2. Static layout: four resizable columns + title/status bars.
3. Real file tree + open files into tabs (read-only) with Prism highlighting.
4. Git panel from `git status` (read-only) → staging + commit → the four diff modes + Split.
5. Search (ripgrep + fuzzy).
6. Terminals via node-pty + xterm.js; run `claude` in the agent pane.
7. Copy reference + Pass-on-to-Agent (clipboard + bracketed-paste into the agent PTY).

## Commands

No build/lint/test commands exist yet. Once the Electron + Vite toolchain is scaffolded, document the real `dev` / `build` / `lint` / `test` commands here, replacing this note.