architecture
How kolu is built
kolu splits the terminal problem across four layers. Close the browser tab, restart the web server, or redeploy the whole thing: your shells, and the agents running in them, keep going.
The stack
Four layers, each with one job. The top two are faces, which come and go. The bottom two are daemons: padi holds the workspace record, and kaval owns the live shells. Kill any layer and everything below it keeps running.
kolu-server binds one padi per host. That set is its host map, which is why kolu-server also holds the Conductor, one agent conversation for the whole fleet.
| Layer | Its one job | Killing it does not lose |
|---|---|---|
PWA client | The view in your browser, one surface consumer per pane. | Nothing. Reload the tab or switch devices and it re-subscribes. It holds no state. |
kolu-server | The web shell: HTTP, the app, websockets. It binds one padi per host and holds the Conductor’s conversation. | Terminal metadata, the remote hosts you added, or the conversation. Each is stored, and the conversation is resumed by its id. |
padi | The per-host workspace daemon: session, awareness, restore. | Terminal state. Records live in its folder on disk, the shells survive in kaval, and it re-seeds in seconds. |
kaval | The shell survivor: it owns the PTYs and their live screens. | The live shells and their scrollback. They live in kaval’s memory, under everything you can restart. |
A deploy adopts what is running
Upgrading kolu does not kill your daemons. A new build adopts the compatible ones, and their live shells, instead of reaping and restarting them. Restore is the path for a daemon that is dead, never for one that is still running. The agents in your terminals survive the upgrade, because they never stopped.
Compared to tmux and zellij
tmux and zellij fold the PTYs, the layout, and the session into one server process. kolu splits them: kaval owns the PTYs, padi owns the workspace. The layer you restart or redeploy is not the layer holding your shells.
| tmux | zellij | kolu | |
|---|---|---|---|
| Detach / close the client | survives | survives | survives — the session lives in the daemons |
| Redeploy / restart the session-UI layer | n/a, no separate layer | n/a, no separate layer | PTYs keep running; the deploy adopts them |
| Upgrade the binary under live sessions | attach breaks on a protocol-version bump | sessions orphaned on a contract-version change | compatible daemon and live PTYs adopted; skewed padi drains, build-skewed kaval stays alive and asks, contract-skewed kaval is recycled |
| Machine reboot | nothing native (a plugin re-runs commands) | re-runs commands (built-in) | re-spawns from padi’s saved session |
| Knows git · PR/CI · agent state | no, status-bar scripting only | no, plugin scripting only | yes, padi derives it |
| Persisted to disk | none native; plugins add layout + cwd | layout + cwd + each pane’s command | records · session · restore target · agent memory |
| Reach | terminal TUI · single host | terminal TUI · single host | browser PWA + kaval-tui; kaval-tui reaches remote hosts over ssh today |
No multiplexer keeps a live process across a machine reboot: a PTY cannot outlive the kernel. All three re-create rather than resume. kolu remembers more about how: the layout, the working directory, the agent that was running, and where to pick it up.
One contract — @kolu/surface
Announcing @kolu/surfaceread the story behind the one contract every layer talks over
@kolu/surface — the docsthe framework's own four-quadrant docs: declare a surface, serve it, daemonize it, and mirror it across an ssh fleet
Every layer talks over the same thing: a typed reactive surface. You declare what a daemon exposes, a handful of primitives plus the verbs that change them, and get a client that stays in sync. Four primitives cover almost everything:
Cell<T>
One value: a snapshot, then live deltas. The session, the version.
Collection<K,T>
Many keyed rows, each independently observable. The terminals registry.
Stream<I,T>
A live view computed over outside state (files, git). Snapshot plus deltas, never stored. A file preview.
Event<I,T>
A point in time: no snapshot, no current value. A terminal exited.
Beside them sit procedures: the verbs you call and await, such as create a
terminal, kill one, or restore a session. That is the whole contract, and it is
served over any transport: in process with no wire at all, over a local unix
socket, over a browser websocket, or over ssh. The ssh transport is how
kaval-tui --host, drishti, and kolu’s remote-host canvas reach a daemon on
another machine. Swap the transport and the client code does not change.
The @kolu/surface docs teach this end to end: your first
surface, make it a
daemon (the pattern kaval and padi are built on),
and across the hosts (the ssh mirror drishti runs).
The framework is not kolu-shaped: drishti is
a separate app built on the same @kolu/surface.
How a daemon is identified
A daemon is its data folder. padi’s identity is its state-root, a durable directory on the host holding its session, its memory and its activity feed. The socket it listens on is named by a digest of that folder, in a scratch directory wiped on every boot.
- A stale lock cannot make a dead daemon look alive. Its socket lives in the boot-wiped directory, gone the moment the machine restarts.
- A dev or test kolu gets its own state-root, so its own padi and its own kaval. It cannot touch your production terminals.
- Binding never silently defaults to production’s folder: a bare launch dies with
one line. Production wrappers supply
$HOME/.local/state/padi, and a client never invents the path over the wire.
Talking over the wire
Everything the browser does flows over a single WebSocket (/rpc/ws) via
Effect RPC, framed as newline-delimited JSON. The
contract lives in one package both sides share, so calls are type-checked when
kolu is built and their payloads decoded by Effect
Schema as they arrive. Two
patterns cover all of it:
| Pattern | Semantics | Used for |
|---|---|---|
| Request / response | a one-shot call you await | create a terminal, kill one, restart a daemon, add a host |
| Subscription | the server pushes values over the socket as a stream | the terminal list, per-terminal metadata, server state |
A subscription becomes a fine-grained SolidJS signal on the client, so one row
changing repaints only that row. The shell CLIs are the exception to the
websocket: kaval-tui and padi-tui reach their daemon over
its local unix socket, with the same ndjson framing.
The Conductor’s tool endpoint
The Conductor’s agent needs kolu’s own tools, and it gets them
over MCP on a dedicated loopback listener of kolu-server’s: 127.0.0.1, an
ephemeral port, no TLS, one endpoint over streamable HTTP. It is deliberately
not a route on the app listener, which is TLS-able, bound wherever you asked,
and gated for browsers by origin.
Its gate is a bearer token, minted fresh for each kolu-server process, required on every request and compared in constant time. Loopback on its own is not a gate, because every other process on the box can reach loopback too. Before opening a conversation against the endpoint, kolu-server makes a real request to it. A conversation that cannot reach its own tools is refused with a sentence naming the URL.
Three loops of data flow
Three loops drive the system. Terminal input and output is the hot path: your keystrokes and the screen. The metadata loop is side-channel enrichment: the git, PR, agent state and output activity that light up the dock. Both run over the browser’s one websocket. The conductor loop is the third, and it touches no browser at all.
Terminal input and output
A keystroke goes over sendInput to the PTY that kaval owns.
kolu-server proxies the browser’s socket to padi, which drives kaval.
Output flows back as an attach stream of typed frames. kaval parses the VT
sequences itself, so a client joining late gets about 4 KB of screen state
instead of a replayed buffer.
| Frame | What it carries |
|---|---|
snapshot | the screen, and the grid it was drawn at |
delta | output, in the order the shell wrote it |
resized | the point where that screen changed size |
A pane resizes its terminal at the resized frame, never when its own box
moves, so it cannot disagree with kaval’s copy about a size.
Each connection carries every terminal’s stream at once. When one stops being read, only that stream waits, and picks up where it left off. A reader far enough behind is re-attached with a fresh snapshot instead.
kaval holds a resize’s repaint back for a moment, then delivers it or drops the
viewers onto the settled screen. Both drops arrive as an overflow frame.
A connection’s keep-alive ping ends a hop that has carried nothing for a full minute. Where a watchdog guards a hop it decides first: the browser’s counts arriving data as progress, the one to a local padi checks that padi is still running, and a remote hop is probed over ssh. There is no watchdog between padi and kaval.
Metadata
Every per-terminal sensor lives in padi. A working-directory change (OSC 7) wakes the git sensor (branch, remote), which wakes the PR sensor (open PR and CI checks). Agent detection tails each agent’s session store. padi folds those observations into each terminal’s record and serves them on one collection the client reads directly. See Agent detection.
Live output activity comes from a layer down. kaval sees every PTY byte and every resize, so it emits a host-global meaningful-output edge, with resizes excluded, which padi folds into a live-dot window.
The conductor loop
kolu-server spawns one ACP adapter (claude) and talks the
protocol to it over stdio. The agent calls
kolu’s own MCP tools back over the loopback endpoint, and kolu-server
answers them out of its host map, so lifecycle_create on prod lands a
terminal in that host’s padi. A terminal is named host/id on that wire.
kolu-server also starts turns itself, watching the same host records the dock is drawn from. A work’s member stopping, asking or leaving, and your answer to its question, each mint a wake that runs a turn as your prompt does. A host without an established roster is read as settling, so no wake says a terminal is gone until a host can say so.
Works keyed by branch, their members by terminal, their Code views and the
memory are four saved keys, served as works,
memberReadings, workCodeViews and conductorMemory. See the
Conductor.
The packages
kolu is a pnpm monorepo. Each hard problem a piece hides (transport, screen rendering, persistence) is its own package, with the dependency arrow pointing out. The map:
| Package | What it does | Depends on |
|---|---|---|
client | The browser app: SolidJS, xterm.js, Tailwind. | padi-client, surface, xterm-kit, theme, kolu-work, the solid-* leaves |
server | The Effect HTTP shell: serves the app, the preview route and the websocket, binds one padi per host, and mounts the Conductor. | padi, padi-client, conductor, kolu-work, surface-remote, port-forward |
conductor | The conversation itself, split by clock: the agent and its transcript, the work, member and Code view stores, observation, wakes and asking. | acp, acp-harness, padi-client, kolu-work, surface |
kolu-work | A piece of work as kolu stores it, and the waterfall’s words. | effect |
kolu-cli | The kolu binary: subcommand dispatch and the terminal verbs ls, create, send, wait, snapshot, history, kill, watch. | padi, padi-client, surface-cli |
kolu-mcp | The agent face, and the one place the exposed tool list is declared: kolu mcp, plus the fleet projection kolu-server serves over a host map. | padi, padi-client, surface-mcp, conductor, kolu-work |
padi | The per-host workspace daemon: it owns the terminal domain and serves padiSurface. Ships padi-tui. | padi-client, surface-daemon, surface-remote, agent-distro |
kaval | The standalone PTY daemon: the shells and their live screens. Ships kaval-tui. | surface-daemon, xterm-kit, terminal-protocol |
padi-client | padi’s other half: the padiSurface contract, the dial that reaches a running padi, the attention fold and the attach consumer contract. | surface, surface-daemon, terminal-vocab |
surface | The framework: Cell, Collection, Stream, Event and the SolidJS hooks. | log |
surface-remote | The ssh mirror, and the closures it lands on a host. | surface, surface-map, shell-quote |
surface-daemon | The durable-daemon spine: identity, drain, the mixed-version test kit, and the supervisor half beside it. | surface, log |
port-forward | Hides ssh forward lifetime and local binding: one dedicated ssh connection per forward, so a forward dies with the process that opened it. | nothing in kolu |
xterm-kit | Hides xterm.js’s hazards (pinned internals, scrollback surgery, write buffering, mirror anchoring, box-to-grid sizing) behind a runtime-neutral core and a /solid adapter. | url-shape |
terminal-snapshot | Turns a screen plus a theme into backend-free drawing instructions, so the browser’s copy-screenshot and kolu screenshot draw the same picture. | html-escape |
acp | The Agent Client Protocol vocabulary, and the pure projections over its payloads. | effect, the SDK |
child | A subprocess as one socket: spawn, drained pipes, a kill with a grace period. | nothing |
acp-client | One agent process speaking that protocol: handshake, sessions, turns, sign-in, typed events out. | acp, child |
acp-harness | One conversation on that client: turns, the rows you read, the state a panel draws. | acp, acp-client |
acp-claude | The Claude Code leg, its model table, and the pinned adapter. | acp |
| agent and forge leaves | One package per agent (claude-code, codex, grok, opencode, pi, xyne, omp), each with its vocabulary and detection adapter. github sits behind anyforge; git covers git itself. | anyagent, the agent-agnostic kernel; kolu-agents lists them |
agent-distro | kolu’s contract with agent-distro: the Nix half builds each host’s agent floor, the TypeScript half reads the bakes, receipts and manifests. | nothing in kolu |
| shared UI leaves | theme, solid-statepip, solid-dockrow (the whole Dock row), solid-logtail, solid-pierre, solid-markdown, solid-fileview, solid-browser, serve-dir, artifact-sdk. | padi-client, theme; several are shared with drishti and olai |
| contracts and utilities | common, terminal-vocab, terminal-protocol, transcript-core, transcript-html, and the zero-dependency leaves log, nonempty, shell-quote, html-escape, byte-units. | nothing |
kolu-server delivers the agents to each host: a content-addressed build off agent-distro’s index, pulled from the cache. See Agents for what lands and when.
The Nix composition follows the same boundaries. The root flake holds only the
runnable kolu packages, their checks and the development shells; the website,
the examples and the Odu CI coordinator each have a flake of their own, outside
nix run .’s graph. Remote provisioning has an exact-source flake, exposing
only the packages kolu’s agent manifest names.
A dial lands the daemon and the client CLIs (kaval-tui, padi-tui, kolu) a
remote terminal needs, so an agent there drives its siblings and reaches the
MCP server.
Other machines
The same surface contract runs over ssh: it is how kolu --host and the
kaval-tui and padi-tui previews drive a daemon on a
machine with nothing pre-installed. See Add another machine,
and From another device for serving the browser UI over
private HTTPS.
Next
Start with the site pages for the named programs; the atlas links go deeper into the working notes behind each piece.