CLAUDE.md

1# Electron Package
2 
3The Nimbalyst desktop app, built with Electron.
4 
5## Development Commands
6 
7- **Dev server**: `npm run dev` (user runs this — don't do it yourself)
8- **Dev with restart loop**: `npm run dev:loop` (enables restart button / `/restart` command)
9- **Build for Mac**: `npm run build:mac:local` or `npm run build:mac:notarized`
10- **Auth callbacks in dev**: no URL-handler setup is required, including for `npm run dev:user2`. Every sign-in flow uses a nonce-protected one-shot listener on `127.0.0.1` owned by the instance that started it.
11- **Other deep links in dev (macOS)**: `npm run dev:url-handler` (from the repo root) points non-auth `nimbalyst://` links at this checkout. The applet in `scripts/install-dev-url-handler.sh` is not part of authentication. The dev app deliberately does *not* claim the scheme itself because all development copies share Electron's `com.github.Electron` bundle id. See `src/main/utils/protocolRegistration.ts`.
12 
13### Testing
14 
15From the repository root:
16- Run one spec: `npx playwright test e2e/monaco/file-watcher-updates.spec.ts`
17- Run a directory: `npx playwright test e2e/monaco/`
18- Run all: `npx playwright test`
19 
20**Always use `npx playwright test` directly.** Never use parallel execution — it corrupts PGLite. See [/docs/E2E_TESTING.md](/docs/E2E_TESTING.md).
21 
22## Architecture
23 
24### Main and Renderer Processes
25 
26Electron apps split into two contexts:
27- **Main** runs Node.js, manages lifecycle, windows, menus, system interactions.
28- **Renderer** runs in a Chromium context; UI only.
29 
30Renderers cannot access Node.js APIs directly — use IPC to request main-process services. For initialization rules (dynamic import in `bootstrap.ts`, lazy init for `app.getPath()` consumers, `safeHandle` / `safeOn`), and cross-platform code patterns, see [MAIN_PROCESS_INIT.md](./MAIN_PROCESS_INIT.md).
31 
32## IPC Communication
33 
34### Preload API
35- **Location**: `src/preload/index.ts`
36- **Exposed as**: `window.electronAPI` (NOT `window.api`)
37- **Generic methods**: `invoke`, `send`, `on` (returns an unsubscribe closure — there is no `off`, see [/docs/IPC_LISTENERS.md](/docs/IPC_LISTENERS.md))
38- Renderer services use these to talk to main-process services.
39 
40### Document Service
41- Main: `ElectronDocumentService` (file scanning, metadata extraction, caching)
42- Renderer: `RendererDocumentService` (facade over IPC)
43- **Metadata**: frontmatter extraction with bounded reads (4KB)
44- **Channels**: `document-service:*`
45 
46### Common IPC Issues
47- `window.api undefined` → use `window.electronAPI`
48- Empty responses → check the window has a valid workspace path
49- Service resolution is keyed off workspace path
50 
51For deep IPC patterns (`safeHandle`/`safeOn`, error handling, channel structure), see [/docs/IPC_GUIDE.md](/docs/IPC_GUIDE.md).
52 
53## Data Persistence
54 
55The app runs over **either PGLite (PostgreSQL in WebAssembly) or better-sqlite3** — both backends are active during the in-progress migration. Code must work on either; do not assume one. **Never use `localStorage` in the renderer.** Persist via IPC to main using:
56- **app-settings store** (`src/main/utils/store.ts`) for global app settings
57- **workspace-settings store** for per-project state
58- **AppDatabase** (PGLite or SQLite, selected at init) for complex data (AI sessions, document history, trackers)
59 
60The biggest divergence to remember: `data->'key'` returns a parsed object on PGLite but a JSON string on SQLite. For tables, locations, shutdown rules, timestamp handling, and the full list of backend-divergent behaviors, see [DATABASE.md](./DATABASE.md).
61 
62## Renderer State Architecture
63 
64The renderer uses Jotai for state that crosses component boundaries. Editors use **EditorHost** — a stable service object — for all host communication; content state lives in the editor, not parent components.
65 
66| Domain | Atoms | Owner |
67| --- | --- | --- |
68| Theme | `themeAtom` | Global, IPC-synced |
69| Editors | `editorDirtyAtom(key)`, `editorProcessingAtom(key)` | EditorHost writes, Tab reads |
70| Sessions | `sessionUnreadAtom(id)`, `sessionProcessingAtom(id)` | AgenticPanel writes, UI reads |
71| File Tree | `gitStatusAtom`, `expandedDirsAtom` | WorkspaceSidebar writes, FileTree reads |
72| Trackers | `trackerCountsAtom` | TrackerService writes, UI reads |
73 
74**Re-render isolation**: parents subscribe to lists of IDs; children subscribe to their own atoms. If you need `React.memo` to prevent re-renders, you have the wrong architecture.
75 
76For full patterns, see [/docs/EDITOR_STATE.md](/docs/EDITOR_STATE.md) and [/docs/JOTAI.md](/docs/JOTAI.md).
77 
78## Logging
79 
80Three log destinations:
81 
82- **Main process log**: `~/Library/Application Support/@nimbalyst/electron/logs/main.log` — main-process events, AI, sync, file ops; categories like `(MAIN)`, `(AI)`, `(API)`, `(SYNC)`.
83- **Renderer console log** (dev mode only): `~/Library/Application Support/@nimbalyst/electron/nimbalyst-debug.log` — captured via `webContents.on('console-message')` in `src/main/index.ts`.
84 
85Use the agent log access tools (`get_main_process_logs`, `get_renderer_debug_logs`) instead of asking users to paste logs. See [/docs/DEBUGGING_LOGS.md](/docs/DEBUGGING_LOGS.md).
86 
87## Window State Persistence
88 
89- **Global session state** restores all windows on restart (bounds, focus order, dev tools state).
90- **Per-project state** restores window configuration, open file, AI panel width and collapsed state, draft inputs.
91- **Session continuity** — chat sessions persist across restarts.
92 
93## Theme Support
94 
95Themes: Light, Dark (#2d2d2d / #1a1a1a / #3a3a3a), Crystal Dark (Tailwind gray scale), Auto.
96 
97**Critical rules:**
98- Never hardcode colors in CSS files — use CSS variables.
99- `src/renderer/index.css` is the only place theme colors are defined.
100- Apply themes by setting both the `data-theme` attribute and the CSS class on the root element.
101 
102Comprehensive: [THEMING.md](./THEMING.md).
103 
104## File Operations
105 
106- **Drag-and-drop**: move files/folders in the Project Sidebar; hold Option/Alt to copy.
107- **Context menus**: rename, delete, open in new window.
108- **File watching**: auto-update on disk changes.
109 
110## AI Providers
111 
112Provider implementations live in `packages/runtime` — see `/packages/runtime/CLAUDE.md`. Electron-only pieces:
113 
114- **Renderer panels**: `src/renderer/components/AIModels/panels/ClaudePanel.tsx`, `ClaudeCodePanel.tsx`
115- **Claude Code installer**: `src/renderer/components/AIModels/services/CLIInstaller.ts` (manages local installation of `@anthropic-ai/claude-agent-sdk`)
116 
117## macOS Code Signing & Notarization
118 
119- **Certificate**: Developer ID Application
120- **Builds**: `npm run build:mac:notarized` (notarized), `build:mac:local` (local testing)
121- **Bundled tools**: ripgrep is signed; JAR files are excluded automatically (can't be notarized)
122- **Entitlements**: hardened runtime with necessary exceptions
123 
124## Git Worktree Integration
125 
126Nimbalyst creates git worktrees for isolated AI coding sessions. See [/docs/WORKTREES.md](/docs/WORKTREES.md). The `worktrees` table stores metadata; `ai_sessions.worktree_id` links sessions to worktrees. IPC channels: `worktree:create`, `worktree:get-status`, `worktree:delete`, `worktree:list`, `worktree:get`.
127 
128## Analytics
129 
130See [/docs/ANALYTICS_GUIDE.md](/docs/ANALYTICS_GUIDE.md). **When adding, modifying, or removing PostHog events, update [/docs/POSTHOG_EVENTS.md](/docs/POSTHOG_EVENTS.md).**
131