Architecture
Architecture
TermPuzzle is a desktop-first app. Your projects, terminals and history live on your machine — not in a cloud you have to trust.
Desktop-first
TermPuzzle runs as a native desktop application, not a web app or a cloud service. It works fully offline: after a license check (valid offline for 14 days), no network connection is required. There is no server that holds your code.
Electron
The app is built on Electron, giving one codebase across macOS, Windows and Linux with native OS integration — window management, the system keychain for secure credential storage, and auto-updates via a built-in updater.
node-pty terminals
Every terminal is a real pseudo-terminal (PTY) via node-pty — the same primitive a native terminal uses. Your shells, dev servers and AI agents run as genuine processes, so anything that works in your terminal works in TermPuzzle.
SQLite (local)
Projects, terminal specs, groups, crew and settings live in a local SQLite database on your machine. It's the source of truth for restore, and it never leaves your device unless you explicitly enable Cloud Sync — which carries only configuration, never your code, terminal output or AI conversations.
Workspace Restore Engine
The restore engine reconstructs a whole workspace from its spec: it relaunches terminal commands, reopens the editor in position, restores agent windows, and lazily mounts projects at boot so startup stays fast. Paths that don't exist on a new machine are re-mapped rather than failing.
Operational State & Project Pulse
TermPuzzle tracks the live state of every process — starting, running, idle, error — and rolls it into Project Pulse, a 0–100 health score. A dropped service is detected, surfaced, and can be recovered automatically, with every launch, recovery and push recorded on the project Timeline.
Workspace Spec
All of the above is described by a plain, committable file. See the Workspace Spec for the format.