kolu
Docs

the workspace daemon & its CLI · alpha

Padi: the memory
under kolu.

padi — the per-host workspace daemon

padi is the per-host daemon that holds what a kolu workspace is: terminals, sessions, restore state, repo context, the code tree, git status, diffs and agent awareness. It sits above kaval, which owns the live shells. padi-tui reads it from the shell.

Where it sits

The browser talks to kolu-server, the server binds padi, and padi supervises its own kaval. Restart the web shell and padi still has the workspace. Restart padi and kaval still has the PTYs. The layers recover on different clocks because they own different state.

kolu-server binds padi, padi supervises kaval, and kaval owns PTYs. padi holds the workspace record while kaval holds the live shells.FACEWORKSPACEPTY OWNERkolubrowser + serverpadisession · registry · agentsthe workspace recordkavalPTYs + screenssurfaceunix socketstate-root on disk

When kaval stops answering

padi supervises its kaval continuously, not only at boot. Every ten seconds it asks three read-only questions over the socket, and a kaval that cannot answer them within five seconds counts as stuck.

What padi seesWhat it does
three stuck answers in a row, about half a minuteruns what the Restart kaval button runs: saves the session, stops the daemon, starts a fresh one, and offers your terminals back for restore
three restarts that still produce no answering daemonstops restarting, and leaves the card and the button for you
the connection drops while the daemon still answersre-makes the line about a second later, backing off to once every half-minute, for as long as it takes

A re-made connection is the ordinary outcome, and it takes the daemon back over. Your terminals and the agents in them keep running, there is nothing to restore, and kolu says so once before the card clears itself.

Two narrower cases end differently, and kolu says which you got. If the daemon exits between the check and the re-connect, the re-connect starts a fresh one. If a re-connected daemon holds terminals kolu cannot account for, kolu replaces it. Both show the restart message, “kaval was unresponsive — kolu restarted it; your session is ready to restore”, and your session comes back through the restore card.

kaval also watches itself from the other side of the wire. It asks its own address a trivial question on the same cadence, and three unanswered self-checks in a row make it exit non-zero rather than accept connections it cannot serve.

While a host’s kaval is down, that host’s dot is amber, not green.

What padi knows

kaval only knows terminals. padi is where terminal observations become a workspace: repo-aware, agent-aware, resumable, and readable from more than one face.

A padi that has just started says it is still settling until it has adopted kaval’s terminals. Only then does it publish an established roster, which names the terminals it holds in the same message. A kaval restart closes the roster to settling again until its terminals are restored.

So a restart or a redeploy is never read a layer up as every terminal dying. Nothing above padi calls a terminal gone until the roster that would have held it is real, and “the roster is real” always arrives with its list of terminals.

padi also keeps account of its own cost: the commands it ran in the last minute, its stalls, its file watchers and its call times. Troubleshooting → kolu feels slow shows where to read them.

terminal registry

which terminals exist, where they belong, and how to re-open them after the web layer moves.

workspace memory

the session record, activity feed, restore target, and durable state-root for one host.

repo context

repo, branch, pull request, checks, cwd, foreground command, file browsing, git status, and diffs.

agent state

whether a terminal’s agent is working, waiting, or asking for you, folded into one live surface.

one host, nothing more

padi knows this machine’s terminals and nothing about any other. The fleet view, and the Conductor’s one conversation, are assembled a layer up, by the kolu-server that binds every host’s padi.

Read the workspace from the shell

padi-tui reads the same workspace surface kolu uses. Where kaval-tui shows what is running in each PTY, padi-tui shows what each terminal is in: repo, pull request, checks, foreground command, live byte activity and agent state. That is the state behind the multi-agent dock.

padi-tui status
padi-tui watch
padi-tui wait a3f10000 --until awaiting,waiting
padi-tui create --toplevel -- claude
ID        REPO·BRANCH         PR        AGENT             FOREGROUND        IDLE
a3f10000  kolu·feat/dial-ssh  #1412 ✓   claude · working  node              2s
b7c20000  kolu·master         —         codex · waiting   codex             1m
c9d40000  kolu·fix/fold       #1408 ✗   —                 nvim              5m

REPO·BRANCH shows — for a terminal outside any repo, and ? while padi has not checked its git yet. With --json, the repo sits under .git.info, and .git.kind says which case it is: repo, none or unresolved.

CommandWhat it does
padi-tui status · --jsonPrint a one-shot workspace snapshot: terminals, repos, agent state, foreground process, and recency.
padi-tui watch · --jsonFollow the workspace live, including state changes and activity indicators.
padi-tui wait <id> --until awaiting,waiting · --timeout <ms> · --jsonBlock until an agent turn ends using padi’s real agent-state fold, not a guess from terminal silence.
padi-tui create (--toplevel | --parent <id>) -- claude · --worktree <branch> · --repo <path> · --jsonCreate a kolu terminal from the shell, live on the canvas. Placement is required: --toplevel, or --parent <id> to split under an existing terminal. Add --worktree for a worktree’d agent.

Which daemon it talks to

  • Inside a kolu terminal, $PADI_SOCKET makes padi-tui flag-less, so an agent driving its siblings never guesses a path. padi keys its socket by a digest of its state-root.
  • padi also puts padi-tui, kaval-tui and the kolu whose mcp face agents connect to on that terminal’s $PATH, taken from padi’s own build. On a remote host they arrive in the closure kolu provisions, so a tool can never come from a different build than the daemon it talks to.
  • Elsewhere it finds the running padi by itself. With several running (your everyday padi plus a dev or test one), it picks the one keyed to the state root your environment names.
  • --socket <path> and --state-root <dir> point it at a different local daemon.
  • --host <ssh> reaches a padi on another machine, the twin of kaval-tui --host. It provisions the daemon with Nix, runs padi --stdio over ssh, and runs every verb unchanged (padi-tui status --host nix@prod).
  • Read verbs are safe over --host, and create lands a real terminal on the host, which survives the link. A tui only dials, so it never drains or converges the remote padi. --host is mutually exclusive with --socket and --state-root.

To point kolu’s browser at a remote padi instead, see Add another machine.

Wait for an agent turn

wait <id> --until awaiting,waiting blocks until a terminal’s agent finishes its turn, read from real padi state rather than guessed from terminal silence.

  • For a robust driver, wait in two phases: --until working for pickup, then --until awaiting,waiting for turn-end, so a stale previous-turn state cannot satisfy the wait early.
  • --until fresh waits for an agent you have just launched to be up, with its screen settled and nothing said to it yet, which padi knows from the process.
  • --timeout <ms> fails loud (exit 2). A terminal that exits first exits 3. --json prints { id, agent }.

Why it is not inside kolu-server

The web server is a face: HTTP, assets, websocket transport. The workspace is a daemon: durable folder, terminal registry, session restore, agent awareness. Keeping them apart means a deploy can replace the web shell without making the workspace disappear.