clave CLAUDE.md

Clave

Mac desktop app for managing multiple coding-agent CLI sessions in parallel. Provider-agnostic: it orchestrates Claude Code (Cmd+N), Antigravity CLI (Cmd+I), and Codex CLI (Cmd+U) sessions side by side, plus plain terminals (Cmd+T) and remote agents over OpenClaw. Electron + React + TypeScript.

Clave's companion agent plugin (clave, exposing /clave:create-workspace and /clave:recover-sessions) ships from plugin/ in this repo — see plugin/CLAUDE.md. It is installed with npx plugins add codika-io/clave, resolved through .claude-plugin/marketplace.json at the root. The Electron app reads installed plugins from ~/.claude/plugins/ at runtime and never reads plugin/ directly; the folder is here so a .clave format change and the skill that describes it land in the same commit (see the schema sync rule below).

Commands

• npm run dev — start dev (Electron window + hot reload)
• npm run build — typecheck + build
• npm run build:mac — build + package macOS universal dmg + zip (signed + notarized)
• npm run typecheck — typecheck only
• npm run lint — eslint
• Releases ship via CI on push to prod (bump from a [minor]/[major] commit-message marker, else patch) — see .claude/rules/release.md. npm run release -- --patch|--minor|--major remains the local fallback.

Architecture

Three-process Electron app:

• Main (src/main/): Electron window, node-pty, IPC handlers, domain managers. PTY spawns /bin/zsh -l -c claude per session. IPC handlers are split into modular files under ipc-handlers/.
• Preload (src/preload/): Typed window.electronAPI via contextBridge. All main↔renderer communication goes through IPC.
• Renderer (src/renderer/src/): React + Zustand + xterm.js + Tailwind v4 + Framer Motion.

Windows (PRDCT-1703): a window is the whole app once more, on whatever workspace the user put it on — several windows may show the same workspace. One main process, one MCP server, one pty-manager, one event store; each window is a renderer with its own Zustand stores. Sessions and groups live in the window they were opened in, and that is all "which window" means: every window has a persisted windowKey (windows.json, src/main/window-state.ts), its own sidebar layout file (sidebar-layouts/windows/<key>.json), and session records carry the key of their home window. The runtime truth (window ↔ key ↔ workspace, session → window) is src/main/window-registry.ts; the lowest-id live window is the primary: it adopts orphans at boot (records and layouts whose window no longer exists) and takes in what a closing window leaves (its tmux-backed tabs re-home there with their groups, ids preserved). Moving a tab or a group between windows is the same detach + re-adopt (window:move-sessions / window:move-group), and the agent tools take a window argument for it. A call from an agent lands in the window holding its subject session, else the window it names, else the caller's window — never a window picked from the workspace argument.