bruceyongli/supercalm

Purpose and entry points

Supercalm is a self-hosted Node.js control plane for persistent claude, codex, and agy coding-agent sessions. It serves a browser/PWA dashboard, exposes HTTP/SSE APIs, and mediates human or autonomous responses. Runtime entry is src/server.js; operational entry points include bin/aios, bin/install-service, and bin/expose.

HTTP server and browser surfaces

src/server.js is the loopback HTTP router, static-file host, and SSE endpoint provider. The primary browser shell is web/app.html and web/app.js; session interaction and terminal/state rendering are concentrated in web/session.js, web/session-viewport.js, and web/story-view.js. Phone-specific use is a separate PWA surface at web/phone.html and web/phone.js.

Control flow is browser → REST/SSE → server → session/store/agent subsystems. Browser clients receive dashboard changes and raw terminal streams rather than directly accessing tmux.

Project, session, and terminal lifecycle

Projects and sessions are modeled and persisted through src/project_graph.js, src/sessions.js, and src/session_storage.js. src/sessions.js owns tmux launch, discovery, capture/tailing, keystrokes, input delivery, resizing, and lifecycle polling. It spawns CLI agents in project working directories, creating a hard boundary between the web/API plane and host command execution.

Terminal output is classified by src/detect.js and src/detect_classify.js into working, waiting-for-input, or exited states. Hook signals from agent CLIs enter through src/hooks.js, improving lifecycle precision beyond terminal heuristics.

Stateful event and evidence layer

SQLite-backed durable state is centered on src/store.js, with session-oriented persistence in src/session_storage.js and projected UI/session state in src/session_projection.js. Records include projects, sessions, events, messages, and push subscriptions. src/records.js and src/story.js organize durable session history into reviewable timelines/transcripts.

This boundary allows tmux processes to survive server/browser disconnects while the dashboard can reconstruct current state and historical evidence.

Supervisor autonomy pipeline

The supervisor is an opt-in, per-session decision system rooted at src/agents/supervisor.js. Its staged control loop spans observation (src/agents/supervisor/observe.js), interpretation and decision (src/agents/supervisor/interpret.js, src/agents/supervisor/decide.js), dispatch/effects (src/agents/supervisor/dispatch.js, src/agents/supervisor/effects.js), and verification (src/agents/supervisor/verify.js).

It applies policy and safety gates before acting: src/agents/supervisor/event_gate.js, src/agents/supervisor/send_policy.js, and src/agents/supervisor/context_guard.js. It retains approved operational judgment and task context via src/agents/supervisor/project_memory.js and src/agents/supervisor/decision_records.js. The critical boundary is that claimed agent progress must be verified against available terminal, worktree, diff, or other evidence before completion is accepted.

Model, voice, and notification integrations

Agent/model selection and optional proxy access are handled by src/model_providers.js, src/model_proxy.js, and src/llm.js; Supercalm consumes external model infrastructure rather than managing the proxy fleet. Optional speech input routes through src/voice.js, src/stt_codex.js, and src/spark.js, which integrate an ffmpeg-assisted recording/transcription flow. TTS is isolated in src/tts.js and src/voice_providers.js.

Waiting transitions can notify remote devices through src/push.js using web-push/VAPID. These integrations are configurable and intended to degrade gracefully when unavailable.

Host deployment, safety, and updates

The service requires Node 22+, tmux, and optionally ffmpeg; it binds locally and is intended to be published through Tailscale Serve or an authenticated reverse proxy. Runtime configuration is centralized in src/config.js. Deployment and release guardrails live in src/deploy_orchestrator.js, src/deploy_breaker.js, and src/update_core.js; operational wrappers are bin/deploy and bin/update.

Host-side command execution is constrained by explicit integration and safety layers such as src/capabilities.js, src/db_guard.js, and scripts/aios-command-guard.sh. Git-based update/release flow and local-only binding reinforce the personal, self-hosted trust boundary.