HQ — Project Dashboard for Windows

A tabbed terminal emulator built for running many Claude Code sessions in parallel.

HQ is a desktop app: split-pane terminals tuned for a workflow where each tab is a Claude session in a different project. The left sidebar surfaces every project HQ discovers under your home directory and the recent jsonl sessions Claude has written there. The right rail renders a live timeline of the focused Claude turn. Tabs flash red and chime the moment Claude is waiting for you, even if the tab is off-screen.

Status: Windows port. Private repo, in iteration. The macOS Electron build it tracks lives elsewhere; this codebase was written from scratch against the spec in PROMPT_B.md.

---

Highlights

• ConPTY-backed terminal pane (xterm.js + node-pty 1.1) with auto-detect for pwsh → powershell → cmd → Git Bash → WSL.
• PTY survives tab switches via a 256 KB ring buffer in main; tabs only kill their PTY on explicit close.
• Sidebar project list scanned from %USERPROFILE%, group dirs (projects/, code/, src/), with stack detection (Next.js / Vite / CRA / Express / Python / Go / Rust / Static / Manual).
• Recent Claude sessions under each project (read from ~/.claude/projects/<flat-cwd>/) — first-prompt preview, ● mark on the tab you're focused on, "in tab" badge for any session already open.
• Live timeline rail — chokidar jsonl watcher + line-buffered turn assembly + heuristic summary; cards render as Ask / Clarify / Reply / Act.
• Attention pipeline (three detectors) — terminal bell, ❯ N. permission-menu scanner, and stop_reason: "end_turn" from the jsonl all fire chime + tab pulse + sidebar dot. Auto-clears when you focus the flashing tab.
• Themes — Workshop (warm charcoal / honey, Instrument Serif italic) and Blueprint (cool charcoal / signal cyan, IBM Plex Mono). Mica or acrylic background depending on Win11 vs Win10. Title-bar overlay color follows theme.
• Open server at 127.0.0.1:4322 — GET /open?dir=…&cmd=…&name=… from any sibling app pops a tab. Plus hq:// URL scheme and hq.cmd CLI shim.
• Right-click menus — projects (open / launch agent / clone / rename / hide), tabs (rename, permission mode, session name), session rows (rename, resume, delete).
• Modals — New Claude Code agent (writes YAML-frontmatter .md to .claude/agents/) and GitHub clone (git clone --depth=50 then opens claude in the new dir).
• In-app git — status / add / diff / log / pull / push / commit / switch / new-branch, sandboxed to %USERPROFILE%, GitHub repo slug rendered in the panel header (click → opens in browser), push toast on success.
• System tray + jumplist + taskbar overlay + flashFrame for attention.

---

Quick start

Dev

npm install
npm run dev

Boots electron-vite with renderer HMR + main live-restart.

Build

npm run build       # bundle main/preload/renderer to out/
npm run package     # NSIS + portable .exe (Win10 1809+, x64 + ARM64)

Run the unpacked build

dist\win-unpacked\HQ.exe

Manual asar repack (if electron-builder symlink-extract trips — see DEFERRED.md D-002)

./node_modules/.bin/electron-vite build
./node_modules/.bin/asar extract dist/win-unpacked/resources/app.asar dist/asar-staging
rm -rf dist/asar-staging/out && cp -r out dist/asar-staging/
./node_modules/.bin/asar pack dist/asar-staging dist/win-unpacked/resources/app.asar

---

Keyboard shortcuts

Action	Shortcut
New tab	Ctrl+T
Close pane / tab	Ctrl+W
Toggle sidebar	Ctrl+B
Toggle timeline rail	Ctrl+R
Split pane vertical / horizontal	Ctrl+D / Ctrl+Shift+D
Cycle tabs	Ctrl+Shift+] / Ctrl+Shift+[
Move tab	Ctrl+Alt+Shift+] / Ctrl+Alt+Shift+[
Jump to tab N (or last)	Ctrl+1..8 / Ctrl+9
Focus pane neighbor	Ctrl+Alt+Arrow (also Alt+Shift+Arrow)
Copy / cut selection	Ctrl+C / Ctrl+X (with selection; passes through to PTY otherwise)
Select all	Ctrl+A
DevTools	Ctrl+Shift+I

---

Tech stack

Electron 33 · electron-vite 2 · React 18 · TypeScript 5.6 · Tailwind 3.4 · Zustand 5 · react-resizable-panels 2 · xterm.js 5 · node-pty 1.1 · chokidar 3.

STACK_DECISION.md has the full pin list and risk register. ARCHITECTURE.md covers the process model, IPC surface, persistence, theming, accelerator routing.

---

Status & deferrals

Phase 1–5	Complete (PORT_STATUS.md is the per-feature tracking sheet).
Phase 6 — packaged installer	Deferred (DEFERRED.md D-002). Toggle Windows Developer Mode → npm run package finishes.
Code signing	Deferred (DEFERRED.md D-001). No EV cert yet. Every fresh install pops SmartScreen until signed.
Auto-update	Wired but dormant. Set HQ_UPDATE_FEED env var to a self-hosted electron-updater feed to enable.

---

Crash dumps + telemetry

Crash dumps land at %LOCALAPPDATA%\HQ\Crashes\. Nothing is uploaded. No telemetry, no analytics. If HQ crashes, ZIP the Crashes dir and attach to a bug report.

Tray icon

Windows 11 hides tray icons by default ("Show notification icons"). If you hide HQ's, attention flashes still reach you via the taskbar overlay icon and flashFrame.

---

Tracking files in this repo

• STACK_DECISION.md — why Electron + the version pins.
• ARCHITECTURE.md — process model, IPC, persistence, theming, accelerators.
• PORT_STATUS.md — every Feature ID with implementation note.
• BUILD_QUESTIONS.md — every uncertainty surfaced + resolution.
• DEFERRED.md — items not in v1, with reason + undo cost.
• VERIFICATION.md — Phase 4 manual smoke evidence per module.
• PARITY_REPORT.md — Phase 5 row-per-feature parity table (Mac vs Windows).