kolu
Docs

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.

The kolu stack, top to bottom: the PWA client in your browser talks over a websocket to kolu-server (the web shell), which binds padi (the per-host workspace daemon), which owns kaval (the PTY daemon) over a unix socket. The client and kolu-server are faces that come and go; padi and kaval are daemons that survive restarts. kaval holds the live PTYs — zsh, claude, nvim. kolu-server also holds the one ACP agent conversation, the Conductor: it spawns the claude adapter and hands it kolu’s own tools over a loopback HTTP MCP endpoint, which reaches every padi in kolu-server’s host map — the local one below it and each remote one over ssh.FACEScome & goDAEMONSsurvivestate below the linewebsocketbind · unix socketunix socketPWA clientthe view in your browserkolu-serverthe web shellpadiworkspace daemon — rememberskavalPTY daemon — keeps shells aliveONE AGENT CHATkolu-server spawns it▸ claude · acpits tools: mcp · loopbackEVERY OTHER HOSTssh▸ padi · prod▸ padi · box-3OWNS THE PTYS▸ zsh▸ claude▸ nvim
LayerIts one jobKilling it does not lose
PWA clientThe 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-serverThe 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.
padiThe 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.
kavalThe 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.

A deploy timeline. In the top lane, the running padi vX drains — saves its session and exits — and the new build padi vY starts and adopts the same kaval. In the bottom lane, kaval runs unbroken straight through the deploy, holding every live PTY, so shells and agents never stop.DEPLOYpadi · vXrunningdrain → respawnsave session · exit · PTYs untouchedpadi · vYthe new buildadoptskavalone process · never restarts here▸▸▸▸▸your shells + agents stream straight through — scrollback intact

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.

tmuxzellijkolu
Detach / close the clientsurvivessurvivessurvives — the session lives in the daemons
Redeploy / restart the session-UI layern/a, no separate layern/a, no separate layerPTYs keep running; the deploy adopts them
Upgrade the binary under live sessionsattach breaks on a protocol-version bumpsessions orphaned on a contract-version changecompatible daemon and live PTYs adopted; skewed padi drains, build-skewed kaval stays alive and asks, contract-skewed kaval is recycled
Machine rebootnothing native (a plugin re-runs commands)re-runs commands (built-in)re-spawns from padi’s saved session
Knows git · PR/CI · agent stateno, status-bar scripting onlyno, plugin scripting onlyyes, padi derives it
Persisted to disknone native; plugins add layout + cwdlayout + cwd + each pane’s commandrecords · session · restore target · agent memory
Reachterminal TUI · single hostterminal TUI · single hostbrowser 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.

// identity: durable, the daemon itself$KOLU_PADI_STATE_DIR or —state-root// production wrappers supply $HOME/.local/state/padi// address: config, wiped on boot$XDG_RUNTIME_DIR/padi-<digest>/sock where <digest> = hash(state-root path)
  • 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:

PatternSemanticsUsed for
Request / responsea one-shot call you awaitcreate a terminal, kill one, restart a daemon, add a host
Subscriptionthe server pushes values over the socket as a streamthe 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.

Three data-flow loops. The terminal I/O loop runs both ways through client, kolu-server, padi, and kaval — keystrokes down to the PTY, the screen (a snapshot, then live deltas and the resize frames between them) back up. The metadata loop flows the other way only: kaval feeds padi — its VT taps drive padi’s git, PR, and agent sensors, and its resize-excluded meaningful-output edge feeds padi’s live-activity fold — and padi pushes the result to the client. The conductor loop is separate and reaches no browser: kolu-server spawns the claude ACP adapter, which calls kolu’s tools back over a loopback HTTP MCP endpoint, and kolu-server serves them from its host map — every padi, local and remote, with each terminal named host slash id. That loop closes the other way too: kolu-server watches the host map’s urgency and terminal rosters for the terminals that are members of a piece of work in progress, and starts a turn of the conversation itself when one of them stops, asks or is gone.TERMINAL I/O — keystrokes ⇄ screenclientxterm.jskolu-serverweb shellpadisensors · foldkavalthe PTYmetadata — kaval → git · PR · agent · live activity (side channel)THE CONDUCTOR — one chat, every hostclaudeacp adapteracpkolu-serverfleet mcp · loopbackhost/idthe host mappadi · local — padi · prod — padi · box-3wakes — a work’s terminal stops · asks · is gone → kolu-server starts the turn

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.

FrameWhat it carries
snapshotthe screen, and the grid it was drawn at
deltaoutput, in the order the shell wrote it
resizedthe 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:

PackageWhat it doesDepends on
clientThe browser app: SolidJS, xterm.js, Tailwind.padi-client, surface, xterm-kit, theme, kolu-work, the solid-* leaves
serverThe 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
conductorThe 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-workA piece of work as kolu stores it, and the waterfall’s words.effect
kolu-cliThe kolu binary: subcommand dispatch and the terminal verbs ls, create, send, wait, snapshot, history, kill, watch.padi, padi-client, surface-cli
kolu-mcpThe 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
padiThe per-host workspace daemon: it owns the terminal domain and serves padiSurface. Ships padi-tui.padi-client, surface-daemon, surface-remote, agent-distro
kavalThe standalone PTY daemon: the shells and their live screens. Ships kaval-tui.surface-daemon, xterm-kit, terminal-protocol
padi-clientpadi’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
surfaceThe framework: Cell, Collection, Stream, Event and the SolidJS hooks.log
surface-remoteThe ssh mirror, and the closures it lands on a host.surface, surface-map, shell-quote
surface-daemonThe durable-daemon spine: identity, drain, the mixed-version test kit, and the supervisor half beside it.surface, log
port-forwardHides 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-kitHides 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-snapshotTurns 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
acpThe Agent Client Protocol vocabulary, and the pure projections over its payloads.effect, the SDK
childA subprocess as one socket: spawn, drained pipes, a kill with a grace period.nothing
acp-clientOne agent process speaking that protocol: handshake, sessions, turns, sign-in, typed events out.acp, child
acp-harnessOne conversation on that client: turns, the rows you read, the state a panel draws.acp, acp-client
acp-claudeThe Claude Code leg, its model table, and the pinned adapter.acp
agent and forge leavesOne 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-distrokolu’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 leavestheme, 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 utilitiescommon, 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.

The repo — juspay/koluevery package, with its full README, in one tree

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.