99 lines
5.0 KiB
Markdown
99 lines
5.0 KiB
Markdown
# 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.
|