plano: Instructions file for Claude Code

CLAUDE.md

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

What PLANO is

A desktop app (Electron): an infinite-canvas workspace IDE. One spatial pan/zoom canvas per project where the user drops floating panels — terminals, code editors, browsers, AI agents, file explorer, git, markdown, sticky notes, text, regions. Layout persists per project. Signature feature: terminals auto-detect when an AI coding CLI (Claude Code, Codex, …) is running inside them and morph into "agent mode".

Full specs live in docs/architecture/ARCHITECTURE.md and docs/design/DESIGN_SYSTEM.md — read them before non-trivial changes. Use docs/README.md as the documentation index.

Commands

npm install            # deps (see Electron-binary gotcha below)
npm run rebuild        # rebuild node-pty against Electron's ABI (needs VS C++ Build Tools on Windows)
npm run dev            # launch with HMR (renderer) + hot-reload (main/preload)
npm run build          # electron-vite production build into out/
npm run typecheck      # tsc --noEmit for BOTH projects (node + web); run before considering work done
npm run typecheck:node # main + preload + shared only
npm run typecheck:web  # renderer + shared only
npm run dist           # build + package an installer (electron-builder)

There is no test runner wired yet and no linter configured (ESLint is referenced in comments but not installed). npm run typecheck is the only automated gate — always run it after edits.

Environment gotchas (Windows — hit these during setup)

• Electron binary may be missing after npm install. Symptom: npm run dev fails with Error: Electron uninstall. Cause: a corrupt zip in %LOCALAPPDATA%\electron\Cache makes @electron/get report a false "cache hit", and Electron's own extract-zip silently stops after the first file. Fix: extract the cached zip manually — Expand-Archive <cache>\electron-v*-win32-x64.zip node_modules/electron/dist -Force then write electron.exe into node_modules/electron/path.txt.
• node-pty is native. npm run rebuild (electron-rebuild) needs the Visual Studio "Desktop development with C++" workload. If it's absent, terminals can't be built from source. In practice the prebuilt node-pty binary for Node 20 has matched Electron 33's ABI, so terminals load without a rebuild — but don't rely on it across Electron upgrades.
• node-pty loads tolerantly: PtyManager lazy-requires node-pty and, on failure, streams a guidance message to the terminal panel instead of crashing the app. Keep that resilience when touching PtyManager.
• Known open issue: under Electron on Windows, node-pty's conpty_console_list_agent can throw AttachConsole failed. This is a ConPTY-console-list problem, not an ABI problem. Wrap mod.spawn(...) defensively when working in PtyManager.