control-room CLAUDE.md

Control Room — Canonical Agent Instructions

Current baseline: v2.0.0, terminal-first.

Product boundary

Control Room is a tmux-like terminal multiplexer with a browser/PWA UI.

Core product scope:

• PTY lifecycle and reconnect;
• multiple terminal panes;
• workspaces;
• single/grid/fullscreen terminal views;
• mobile terminal UX and safe areas;
• rename/duplicate/move/focus/close;
• terminal history and restore;
• terminal templates;
• cwd/file-picker helpers;
• broadcast input;
• lightweight terminal/host status;
• optional CLI launch profiles and activity decoration.

Out of scope:

• provider/account or credential management;
• browser automation;
• cron/job orchestration;
• AI supervisory orchestration;
• managed application lifecycle platforms;
• project-specific runtime dependencies;
• deployment orchestration unrelated to deploying Control Room itself.

A CLI inside a pane manages its own auth, tools, browser work, deployments, and agent behavior.

Architecture

browser / PWA
  -> SvelteKit 2 + Svelte 5 frontend (Node 22 production runtime)
       -> authenticated HTTP proxies
       -> terminal output to browser over SSE
       -> frontend server is the WebSocket client to the agent
  -> Node 22 host agent on loopback
       -> node-pty
       -> bounded host/file/state helpers required by terminal UX

The frontend never shells out directly and never exposes AGENT_GATEWAY_SECRET or CONTROL_ROOM_SECRET to browser JavaScript.

Standalone rule

The repository must remain independently understandable and runnable. Do not add architecture, docs, configuration, imports, or runtime requirements that assume another internal repository exists.

Optional third-party CLI programs may be launched as normal terminal processes. Their existence is not a Control Room runtime dependency.

Frontend rules

• SvelteKit 2 + Svelte 5 runes.
• Use $props(), $state, $derived, $effect, snippets, and rune-backed state modules.
• Do not introduce legacy export let, $:, on:click, legacy <slot>, or writable/readable store patterns in modified code.
• UI primitives: frontend/src/lib/components/ui/.
• Terminal features: frontend/src/lib/features/terminals/.
• Server-only helpers: frontend/src/lib/server/.
• Route APIs: frontend/src/routes/api/**/+server.ts.
• Preserve safe-area, mobile keyboard, fullscreen, viewport and xterm-fit behavior.
• Preserve the app-chrome hierarchy: compact app/status bar → workspace rail → session/command bar → terminal stage; collapse labels/secondary utilities before allowing toolbar wrapping.
• Keep /landing presentation-only and public: prerendered, csr = false, no host/gateway reads, no external runtime resources, route-specific SEO/structured data, and prefers-reduced-motion support.
• Delete obsolete implementations; do not keep compatibility placeholder files.