# Helder

**A dark, AI-first desktop code workbench for reviewing code written by an AI agent.**

Helder is an Electron app that puts code review, git, and a live Claude Code agent side by side in one dense, IDE-style window. It opens one project per window, is dark-only by design (no light mode, no theme toggle), and is built around a single idea: make it effortless to point an AI agent at exactly the code you're looking at.

> **Status: greenfield.** This repository currently contains the design handoff only — no application code yet. The first task is to scaffold the Electron app and port the prototype. See [Getting started](#getting-started).

---

## What it does

A four-column workbench, left to right, between a thin title bar and status bar:

1. **Source Control** — git working state: commit box, staged list, changes list, per-file `+/−` counts. Stage, unstage, commit, and discard. (Push, pull, fetch, and branch switching are out of scope this version.)
2. **Explorer** — a VS Code-style file tree with colored file-type icons and inline change badges.
3. **Editor** — tabs plus syntax-highlighted code, with four diff view modes for changed files: **Original · Updated · Diff · Split** (Split goes full-screen, side by side).
4. **Right column** — a live **Claude Code agent** terminal stacked over a normal shell terminal.

Every pane boundary is a draggable splitter; positions persist across launches.

### The defining feature: Copy reference / Pass on to Agent

Right-click in the editor to copy a project-relative `path:line` reference (e.g. `src/Http/Controller/UserController.php:42`), or **Pass on to Agent** — which inserts the reference into the agent's input *without submitting*, so you can stack several references before sending. Under the hood this uses bracketed paste into the agent's PTY, exactly how a real terminal paste behaves.

### One search for everything

`⌘F` / `Ctrl+F` opens a single modal that searches **both file contents and file names** at once — content matches on the left (ripgrep), fuzzy file-name matches on the right. There is intentionally no separate "go to file" command.

---

## Tech stack

| Layer | Choice |
|-------|--------|
| Shell | Electron (latest stable), main + renderer + preload bridge (`contextIsolation: true`) |
| Renderer | React 18 + TypeScript + Vite (`electron-vite`) |
| Highlighting | Prism 1.29 (swappable to Shiki / CodeMirror 6) |
| Filesystem | `fs` + `chokidar`, via the main process |
| Git | `git` / `simple-git`, via the main process |
| Terminals | `node-pty` + `xterm.js` |
| Search | `ripgrep` (content) + a fuzzy matcher (file names) |
| Mono font | JetBrains Mono, bundled locally |

**Architecture rule:** the renderer never touches the filesystem, git, or PTYs directly. All of it goes through the main process over IPC / the preload bridge.

---

## Getting started

> No build tooling exists yet. This section will be filled in once the Electron + Vite toolchain is scaffolded.

Planned implementation order:

1. Electron shell + frameless dark window; port design tokens to CSS variables; 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` → 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.

To preview the design prototype now, open `design_handoff_helder_workbench/design/Helder - AI Code Workbench.html` in a browser — it's a clickable React-via-Babel mock with sample data.

---

## Configuration

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

- **`.helder/config.json`** — your overrides only (sparse).
- **`.helder/config.default.json`** — the full default set, regenerated on every launch as live documentation of every setting.
- **`.helder/theme.css`** — a custom theme layered over the built-in dark theme; the code font and size live here.

An effective setting is the value from `config.json` if present, otherwise from `config.default.json`, merged key by key.

---

## Repository layout

```
DESIGN.md                          Functional/UX spec — every panel, state, and interaction
CLAUDE.md                          Guidance for Claude Code working in this repo
design_handoff_helder_workbench/
  README.md                        Technical handoff — structure, design tokens, integration mechanics
  design/
    Helder - AI Code Workbench.html  Clickable prototype (open in a browser)
    styles.css                       Canonical design tokens (the :root block)
    src/*.jsx                        Prototype components (reference only — replace mock data)
```

The two handoff documents are the source of truth: **`DESIGN.md`** for *what the app does*, **`design_handoff_helder_workbench/README.md`** for *how to build it*. The prototype is a visual reference — do not ship it as-is.

---

## License

TBD.