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.