supermu / architecture
Persistence is architecture,
not session restore.
Most tools that promise to save your session snapshot it and hope to put it back together later. supermu is built the other way round: the process design makes it structurally impossible for a closing window — or a crashing runtime — to take your work with it. Three roles, each allowed to fail independently.
Three roles, three failure domains
01 · the brain
Coordinator
One daemon keeps the map: workspaces, sessions, activity, budgets, schedules, permissions — all persisted to SQLite. It is the single writer to that database, and every state change appends its event in the same transaction, so the record and the facts can never disagree. It can be killed and restarted at any moment without a single session noticing.
02 · the muscle
Holders
Each session gets a deliberately boring little process that owns its terminal and child process group. Holders detach at spawn, survive the coordinator's death, and are re-adopted when it comes back — the coordinator reconciles to what the holders actually hold, never the other way round. If the part that owns your work can't crash interestingly, your work can't be lost interestingly.
03 · the windows
Clients
The CLI today, native Mac and iPhone apps next — all stateless views over one versioned protocol. A client holds no session data of its own: it renders what the runtime knows and sends requests. If closing a client could destroy work, the architecture would be wrong. It can't, so it isn't.
The consequence: your terminal, your client, and the runtime itself can each go away — separately or together — and the sessions keep running. Reconnect and the coordinator hands you back the same terminals, with their history, exactly where they were.
Invariants the runtime is built on
Every one of these comes from a public architecture decision record in the runtime repository — written before the code, kept honest by it.
State changes and their events are one transaction
The coordinator is the single writer to SQLite, and every mutation appends its event atomically. Anything a client or agent observes on the event bus is a fact that is also durably recorded.
Holders are the source of truth for live sessions
On restart the coordinator adopts running holders and reconciles its database to them — it never assumes a stale row over a live terminal.
Requests are idempotent
Every mutating request carries an id; retries return the original outcome instead of doing the work twice. Flaky networks can't double-spawn a session or double-send input.
The default runaway response is pause, not kill
When budgets trip or something loops, supermu suspends the session with everything intact so you can inspect and decide. Losing work is never the safety mechanism.
The terminal is an interface, not the product
Sessions are addressable objects with identity, state, history, and events. A terminal screen is one way to look at one — the same session is equally a thing an agent can inspect through the API.
The same rigour applies to authority
The process model keeps work alive; the security model decides what that work is allowed to do. It gets the same treatment — designed up front, stated honestly. Read the security model →