parallel-code

# Parallel Code

Electron desktop app for running coding agents in isolated Git worktrees. Desktop releases target **macOS and Linux only**. The phone UI is a separate web frontend.

- **Frontend:** SolidJS, strict TypeScript, Vite.
- **Backend:** Node.js, Electron, node-pty.
- **Package manager:** npm. CI uses Node.js 22.
- Shared project guidance lives here; `CLAUDE.md` imports this file. Keep personal model and workflow preferences in global instructions.

## Development and verification

- `npm run dev` starts the Electron development app.
- `npm run build` builds and packages the app; `npm run build:remote` rebuilds the phone UI.
- `npm run typecheck` checks frontend types and their imports; it does **not** cover the entire Electron backend. `npm run compile` checks backend TypeScript and emits `dist-electron/`.
- Run focused tests while developing:
  - `npm run test:unit -- path/to/file.test.ts` for logic/backend tests (Node environment).
  - `npm run test:client -- path/to/file.client.test.tsx` for DOM/component tests (happy-dom).
- For code changes, run `npm run check` and relevant tests before handoff. It runs backend compilation, frontend type checking, lint, and a formatting check. For documentation-only changes, check the changed files with Prettier.
- `npm test` runs both test suites. `npm run test:ci` adds unit coverage thresholds. `npm run check:static` includes dead-code and architecture checks as well as type checking and lint; use it when changing exports or module dependencies.
- See `.github/workflows/ci.yml` for the complete CI sequence, including security-rule fixture tests and the real-PTY coordinator test. Ordinary test runs skip opt-in PTY, Docker, and real-agent suites; real-agent tests can launch paid services. Report skipped or unavailable verification.
- CI tests that Semgrep rules work on fixtures; it does not scan the repository with Semgrep. `npm run lint:security` and `npm run lint:secrets` run separate scans and require Semgrep and Gitleaks respectively.
- happy-dom cannot verify native Electron views. For browser-preview changes, follow the native smoke checks in `docs/browser-preview.md`.

When committing, use conventional commit messages, such as `fix(terminal): restore focus`. Git hooks enforce the format and run `lint-staged`, `npm run check`, and a lockfile check on commit; pushing runs `check` and `npm test`. Changes to `package.json` must include the corresponding `package-lock.json` update.

## Architecture and conventions

- Use SolidJS function components, signals, and stores. Preserve reactive property access and clean up subscriptions, timers, and terminal resources when their owner is disposed. The component convention does not prohibit utility classes.
- Keep strict TypeScript; use `unknown` and narrow it instead of introducing `any`. Lint treats warnings as failures, including non-null assertions.
- Use the existing loggers in `src/lib/log.ts` (desktop renderer) and `electron/log.ts` (main). Lint permits `console.warn` and `console.error`, but rejects other console methods unless explicitly exempted.
- Follow the existing store domain modules. `src/store/core.ts` owns the main store; `src/store/store.ts` re-exports domain operations.
- Electron TypeScript uses NodeNext resolution: follow existing relative imports with `.js` suffixes.
- Desktop renderer/main communication uses Electron IPC. The phone UI uses the existing HTTP/WebSocket API. Renderer imports of backend code are restricted to the shared modules allowed in `.dependency-cruiser.cjs`.

### IPC changes

- Named channels originate in `electron/ipc/channel-manifest.json`; `electron/ipc/channels.ts` exports the manifest and its type.
- When adding a named channel, update the manifest and the inline allowlist in `electron/preload.cjs`, plus the handler and frontend call site as needed. The sandboxed preload cannot require the local JSON manifest.
- Desktop frontend helpers are in `src/lib/ipc.ts`; handlers are registered in `electron/ipc/register.ts` and subsystem registration modules such as `electron/documents/register.ts`.
- Dynamic `channel:<uuid>` streams are managed by `Channel<T>` and are separate from manifest entries.
- Run `npm run test:unit -- electron/preload-allowlist.test.ts` after changing named channels or the preload allowlist.

### Worktree and runtime boundaries

- Worktree cleanup must not follow symlinks into the main checkout. Preserve the handling in `electron/ipc/worktree-cleanup.ts`.
- Subtask instructions injected by the app are temporary runtime content. Keep them out of committed project guidance. When editing instruction-file handling, read `electron/mcp/preamble.ts`; do not copy its reserved delimiter strings into these guidance files, because cleanup treats them as runtime markers even inside Markdown examples.
- Preserve remote token roles and task scoping. Keep coordinator tokens out of shared URLs and bearer tokens out of logs; reuse the validation and redaction helpers in `electron/remote/server.ts`.
- Use the existing atomic-write helpers in `electron/mcp/atomic.ts` for coordinator persistence. Validate setup inputs before filesystem side effects; see `.semgrep/filesystem-safety.yml`.

## Where to look

- `src/components/`, `src/lib/`, `src/store/`: desktop UI, frontend utilities, and app state.
- `electron/ipc/`: terminal, Git/worktree, task, persistence, and other desktop handlers.
- `electron/mcp/`: MCP server and subtask coordinator; `electron/agent-hooks/`: agent lifecycle hooks.
- `src/remote/`, `electron/remote/`: phone UI and its server.
- `src/documents/`, `electron/documents/`: document workspaces; see `docs/document-workspaces.md`.
- `docs/browser-preview.md`: native browser architecture, limitations, and verification.
- `docs/architecture-overview.html`: broader architecture overview. New files under `docs/` are ignored unless explicitly included in `.gitignore`.