CLAUDE.md · 0-AI-UG/cate

Sections

1. Before You Code
2. Project Overview
3. Build System
4. Dependencies
5. Architecture

First lines (shown under the repo's MIT license)

# CLAUDE.md

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

## Before You Code

Read and follow the **karpathy-guidelines** skill (`.claude/skills/karpathy-guidelines`) when writing, reviewing, or refactoring code here — surface assumptions, make surgical changes, keep it simple, and define verifiable success criteria.

## Project Overview

Cate is a desktop application that provides an infinite zoomable canvas where
terminal, editor, browser and review panels float spatially (similar to
Figma/Miro, but for coding), next to classic docked layouts. Built with
Electron + React + TypeScript, styled with Tailwind CSS.

Each open workspace is served by its own **runtime daemon**, which holds the
workspace's state and does all its work (files, git, terminals, agents,
the `cate` API). The desktop app and the iOS app are clients of those
runtimes; other devices connect to the same runtime after pairing, and every
client sees one live workspace.

`docs/architecture.md` is the model: what every module is, where it lives,
what it owns and how the pieces talk. Read the sections for the area you touch
before changing it. Where the code disagrees with the document, the document
wins.

## Build System

The Electron app lives at the project root. It uses **electron-vite** for the
desktop shell and **esbuild** for the daemon and the CLI.

```bash
npm install              # install dependencies
npm run dev              # bundle the daemon, then start the app with hot reload (CDP on 9222; CATE_CDP_PORT=0 turns it off)
npm run build            # production build of the desktop shell
npm run build:runtime    # bundle the daemon to dist-runtime/runtime.cjs
npm run build:mobile     # bundle the iOS app's client core to ios/Cate/Core/Web/core.js
npm run runtime:tarball  # build the runtime tarball (daemon, Node, cate CLI, skills)
npm run runtime:dev      # install this checkout's runtime into ~/.cate/runtime/<build>/ (no tarball; run by predev)
npm run typecheck        # tsc --noEmit
npm run lint             # eslint
npm run lint:deps        # dependency-cruiser: layer, side and entry rules
npm test                 # vitest suite
npm run test:e2e         # playwright e2e suite (e2e/)
```

Tests use **Vitest** and live alongside the code they cover (`*.test.ts` runs
in node, `*.test.tsx` in jsdom). A few git-touching tests assume a clean
working repo and may fail when the dev tree has a branch named `main` or local
modifications: those failures are environmental, not regressions.

The daemon is a detached process that outlives the app. The app installs the
runtime tarball of its build into `~/.cate/runtime/<build>/` once (in a
checkout, the one `npm run runtime:tarball` left in `dist-runtime/`) and
starts workspaces from there. To iterate on runtime-side code, run the app
with `CATE_RUNTIME_BUNDLE=dist-runtime/runtime.cjs` (it then starts the daemon
from that bundle with your `node`), rebuild with `npm run build:runtime`, and
stop the running workspace runtime so the next open starts the new build.
Without `CATE_RUNTIME_BUNDLE`, the app needs a runtime of its build (a hash of
`src/`, `skills/` and the lockfile): `npm run dev` installs one with `runtime:dev` (instant when the build
is already installed, a few seconds otherwise), so no tarball is needed.

## Dependencies

Managed via npm (`package.json`):
- **Electron**: desktop shell (Chromium + Node.js)
- **React 18** + **react-dom**: UI
- **xterm.js** (`@xterm/xterm`): terminal view; `@xterm/headless` + serialize addon keep each PTY's screen in the runtime
- **node-pty**: PTYs (runtime)
- **Monaco Editor** + **yjs** / **y-monaco**: editor, one shared Yjs buffer per open file
- **zustand**: client-side stores
- **@parcel/watcher**: workspace file watching; **chokidar**: state-file external-edit watching
- **simple-git**: git operations
- **@noble/curves**, **@noble/ciphers**, **@noble/hashes**: the Noise handshake for network connections
- **ws**, **bonjour-service**, **node-datachannel**: same-network WebSocket, mDNS, WebRTC (Cate Connect)
- **lucide-react** / **@phosphor-icons/react**: icons
- **electron-updater**: auto-update (GitHub Releases)

## Architecture

### Processes

- **Runtime daemon** (`src/runtime/daemon/`), one per workspace, on the
  machine that holds the workspace. The same program (`runtime.cjs`, installed
  under `~/.cate/runtime/<build>/`) runs on every machine. It serves the
  workspace over a local socket (`~/.cate/workspaces/<runtimeId>/runtime.sock`,
  which is also the one-daemon-per-workspace lock) and, with network access
  on, over the same network or Cate Connect, always inside a Noise handshake
  with pinned keys; only paired devices connect.
- **Desktop shell** (`src/shells/desktop/`):
  - `main/`: Electron main: windows, menus, native dialogs, updater (and
    installing the bundled runtime tarball), device files, the raw sockets
    for the client's transports (finding and starting local runtimes),
    webview partitions and the loopback web proxy, passkeys, capture, drag
    ghost.
  - `preload/`: `window.cateDesktop` (typed by `DesktopApi` in
    `shells/desktop/contract`). Desktop IPC only; no workspace work crosses
    it. Each preload entry must bundle self-contained (a test enforces it).
  - `renderer/`: boots the client core, installs the desktop `ClientUi` and
    ports, maps each panel type to its view, mounts the desktop UI.
  - `ui/`: the whole desktop UI in React (see "Shared core, one UI per
    shell" below).
- **iOS app** (`ios/`, SwiftUI) with its TypeScript side in
  `src/shells/mobile/`: the client core runs headless in a hidden web view
  (`core/`, bundled by `npm run build:mobile`); `contract.ts` is the bridge
  and the core API between them.
- **CLI** (`src/cli/`): the `cate` command in terminals the runtime spawns.

The client talks to a runtime only through the runtime protocol
(`kernel/rpc`): typed capabilities declared once with `defineCapability`, and
session channels for panels. There is no per-feature IPC.

### Layers and sides

`src/` is organised by **layer**, lowest first:

- `kernel/`: rpc, api, settings, lifecycle, state, log, interaction (generic machinery)
- `runtime/`: daemon, data, transports, security, pairing, connect, tunnel, power, push
- `workspace/`: document, lifecycle (trust), canvas, files, repository, skills, relations, notifications
- `services/`: terminal, browser, agents
- `client/`: core (the client core's entry), connections, workspaces, document mirror, host
- `panels/`: framework + terminal, editor, browser, review, canvas, surface
- `shells/`: desktop (including all desktop UI), mobile (the iOS app's core)
- plus `cli/` and `test/` (test support)

and by **side** inside each module:

```
<module>/
  contract.ts   pure: types, pure logic; re-exports contract/
  contract/     capability.ts (defineCapability), api.ts (cate API specs),
                settings.ts (settings slice), other pure files
  runtime/      daemon side
  node/         Node code shared by the daemon and the desktop shell
  client/       client core: logic, no React, no DOM, no Node, no Electron
  desktop/      desktop-only code that is not UI (webview host, preloads)
```

Rules (enforced by `npm run lint:deps`, `.dependency-cruiser.cjs`):
- Contracts are pure (no Electron, Node built-ins, React, DOM or I/O) and
  import only contracts.
- `runtime/` imports contracts, `runtime/` and `node/`; `client/` imports
  contracts and `client/`; `desktop/` and the desktop shell never import a
  `runtime/` side.
- React, the DOM, xterm, Monaco and the icon sets are imported only in
  `src/shells/desktop/`.
- A module imports only its own layer or lower. A lower layer that needs a
  higher one owns a slot the higher one fills (`runtimeFor` in `kernel/rpc`
  filled by `client/core`; `registerPanelCloseGuard` in `client/host`
  filled by a shell's panel views).
- Across modules, import a contract or a side's `index.ts`, never internals.
  `src/panels/{definitions,runtime,api,capabilities,settings}.ts` are public entries too.
- The daemon's composition root (`src/runtime/daemon/entry.ts`, `main.ts`,
  `compose/`) builds and wires every module's runtime side and is the only
  code exempt from these rules. Runtime sides export factories taking an
  explicit deps object (`createFilesRuntime(deps)`) and a
  `<name>CapabilityImpl`; no globals or singletons.

Path aliases: `@kernel/*`, `@runtime/*`, `@workspace/*`, `@services/*`,
`@client/*`, `@panels/*`, `@shells/*`.