the PTY daemon & its client · alpha
Kaval: a watch over
your terminals.
kaval (Tamil kāval, watch or guard) is a standalone PTY daemon. It owns your shells, mirrors their screens, and serves them over a local unix socket, outliving the clients that come and go. kaval-tui is its terminal client: list, create, snapshot, attach, send input, kill.
How it fits together
One daemon owns the terminals and everything else is a client. kolu’s per-host daemon, padi, spawns a kaval of its own and dials it over a unix socket, exactly as kaval-tui does from the shell.
The link runs both ways: kaval streams live updates back to every client, so a terminal you create from the shell shows up in kolu the moment it is born. You can also run the pair on a machine where kolu has never been installed.
Architecture shows how the layers survive restarts, and the daemon spine documents the single-instance gate and live recycle kaval is built on.
Run the pair
-
Start the daemon. It claims its socket and stands watch — leave it running in a pane, a service, wherever.
nix run github:juspay/kolu#kaval -
Drive it from any other shell. kaval-tui finds the running daemon on its own — no socket path to remember.
nix run github:juspay/kolu#kaval-tui -- create nix run github:juspay/kolu#kaval-tui -- list nix run github:juspay/kolu#kaval-tui -- attach <id> nix run github:juspay/kolu#kaval-tui -- kill <id>
Drive a running kolu
The terminals you have open in kolu are terminals of a kaval, so the same kaval-tui reaches them from the shell with no flags:
kaval-tui list # the terminals open in your kolu
kaval-tui snapshot <id> | grep BUILD-
kaval-tui history <id> --lines 200 # older scrollback above the screen
kaval-tui finds the daemon by scanning the per-user runtime directory, which holds a standalone kaval and the kaval of every kolu on the machine. One running daemon is picked automatically. With more than one, kaval-tui lists them, labelled by the kolu they belong to, and asks you to choose with --socket <path>.
Two environment variables inside a terminal
A terminal kaval spawns carries two variables, so an agent inside it can find its own daemon and its own tile with no flags to pass:
| Var | Names | An agent uses it to |
|---|---|---|
$KAVAL_SOCKET | the socket of the kaval that owns this terminal | point straight at its own daemon: kaval-tui list --socket "$KAVAL_SOCKET", the unambiguous answer when several daemons are up |
$KAVAL_TERMINAL_ID | the id of this terminal | act on itself without being told which tile it is: kaval-tui snapshot "$KAVAL_TERMINAL_ID" --socket "$KAVAL_SOCKET" reads its own screen |
- A kolu started inside a kolu terminal re-stamps its own id and socket over the inherited ones, so both always name this terminal.
- A terminal adopted across an upgrade without a respawn may carry neither. Fall back to
kaval-tui list. - A terminal from
kaval-tui create --hostgets$KAVAL_TERMINAL_IDbut not$KAVAL_SOCKET: the id means the same anywhere, a local socket path does not.
Reach a remote kaval — over ssh
--host <ssh> drives a kaval on another machine, with nothing to install there first. kaval-tui provisions the daemon with Nix (it ships the right-arch build over ssh and installs it), runs it, and dials it. Every subcommand works exactly as it does locally.
kaval-tui create --host nix@prod
kaval-tui list --host nix@prod
kaval-tui attach --host nix@prod <id>
- The remote daemon is durable: a terminal you create outlives the ssh link, so you can attach to it after closing the laptop and changing networks.
- There is one shared daemon per host.
--hostis mutually exclusive with--socket. - It needs passwordless ssh, and your user trusted by the remote machine’s Nix daemon.
- A remote terminal runs in the host’s environment: its
$SHELL,$HOMEand$PATHcome from the remote machine. - Only your terminal’s presentation variables (
TERM,COLORTERM,LANG/LC_*) cross the wire. Your local environment, and any secrets in it, never does.
This is shell-level remote control. From another device is the separate browser path.
What kaval owns
Under the daemon sits one primitive, a multi-client PTY owner. Each PTY is a real shell child paired with a headless screen mirror, fanned out to any number of consumers. It knows nothing about git, pull requests, agent detection or any wire protocol.
race-free, bounded attach
A late-joining client gets a screen snapshot and then live deltas with no
gap and no overlap. The snapshot is bounded to the recent screenful, so a
cold or cross-host attach paints at once instead of replaying the whole
10,000-line mirror. Older history streams in as the client scrolls up
(getHistory).
The attach carries your grid: the daemon resizes the terminal to it and serializes as one act. A terminal has one size, so this is last-attach-wins, and attaching from a differently sized window resizes it for every other viewer too.
drop-slow-subscriber
A wedged client that stops draining its output is dropped, rather than pinning the daemon’s memory without bound. kaval-tui then re-subscribes on its own and gets a fresh snapshot.
kaval surfaces five taps per terminal:
| tap | source |
|---|---|
screen | snapshot + live deltas |
cwd | from OSC 7 reports |
title | from OSC 0/2 changes |
command | from OSC 633 preexec |
exit | the child’s exit code |
What lives above it
padi is the workspace daemon above kaval. It folds those terminal observations into repo context, pull request state, agent state, session restore and the padi-tui surface. The workspace table, padi’s socket discovery and its agent-state waits live there.
Why kaval-tui send, not a message bus
Driving one agent from another means typing a prompt and pressing Enter: raw bytes into the PTY, raw output back. kolu never edits your ~/.claude (or codex, or opencode) config and ships no per-agent glue. Any agent CLI drives the same way (claude, codex). A message bus such as hcom installs hooks into each agent’s config instead.
Content travels by file instead. One agent writes a file the other reads, as the /debate skill does, and kolu watches the working directory, so a new file arrives as a push. kaval-tui send therefore delivers the prompt and nothing bigger.
The screen is still the only place one thing shows: a Claude Code AskUserQuestion or plan-approval menu is in no log or file until after you answer, so you read the rendered screen and answer with arrow keys. The hcom vs. kolu note carries the full argument.
Commands · kaval-tui
| Command | What it does |
|---|---|
kaval-tui list · --json | One row per live terminal — id · pid · idle · cmd · cwd. --json emits an array for jq. |
kaval-tui create · [-- cmd] · --env K=V · --json | Spawn a new terminal on the daemon and print its short id. |
kaval-tui snapshot <id> · --viewport · --tail N | Print a terminal’s rendered screen as plain text and exit. |
kaval-tui history <id> · --lines N | Dump the scrollback above the current screen. |
kaval-tui attach <id> · --escape <char> | Take the terminal over, full screen. Every keystroke and chord reaches the inner program, and your window size follows along. |
kaval-tui send <id> [text...] · --file <path> · --paste/--no-paste · --key <name> · --json | Write input to a terminal without attaching, so one agent can drive another. |
kaval-tui wait <id> --until <cond> · --timeout <ms> · --json | Block until a terminal’s raw output meets a condition, then exit. |
kaval-tui kill <id> | End a terminal the daemon owns. The PTY is torn down, so it drops out of list and any attached client sees the shell exit. Exits 0 on success. |
<id> is the short id or any unique prefix. An id that matches nothing fails loud rather than silently doing nothing.
Create a terminal
kaval-tui create spawns a plain $SHELL, or a command you pass (create -- htop -d 5), and prints its short id. A freshly started daemon owns nothing, so create is what attach needs first.
- The terminal’s environment is a clean canonical base: functional (
HOME,PATH,SHELL, …), presentation (TERM/LANG/…), and login-session capability variables (XDG_RUNTIME_DIR,SSH_AUTH_SOCK,TMPDIR, …). - It is not a copy of your shell’s environment. A variable you exported does not follow in, though an interactive shell still sources your rc files.
- Add specific variables with
--env K=V, which repeats. --jsonemits{ id, pid, cwd }.
Read a terminal’s screen
kaval-tui snapshot <id> prints the rendered screen as plain text and exits, built for piping and grepping. Its trailer line goes to stderr, so stdout stays clean.
- It defaults to the full scrollback.
--viewportprints just the visible screen, the daemon’s own last screenful, which is the right read when driving an agent.--tail Nprints the last N rendered lines. kaval-tui history <id>dumps the older scrollback above the current screen, whichsnapshot --viewportcannot show. It is VT-serialized, so colours survive, and paged from the newest older lines back.--lines Nprints the one page immediately above the screen. Omit it for the full older history, oldest first.historyis read-only and takes no TTY.
Send input to an agent
kaval-tui send <id> writes input without attaching, such as a prompt to a claude, codex or opencode agent running in the terminal.
sendwrites exactly the text or the--keys you pass, never both, and adds no Enter of its own.- Submitting is its own step: send the text,
wait --until idle:<ms>to observe the TUI settle, thensend <id> --key Enter. A same-breath Enter races the TUI’s paste debounce and is dropped. --file <path>reads the text straight from a file, byte-exact, with no"$(cat)"shell mangling.- Multiline text,
--fileand piped stdin go as one bracketed paste, so they do not submit line by line.--keyalso sends control keys (Escape, C-c, Up…). - A write that cannot complete fails loud in seconds instead of hanging.
--jsonemits{ id, bytes, paste, keys }.- A paste large enough for Claude Code to fold into a placeholder does not reliably submit on Enter (#1702). The three-step flow above is verified for normal-size prompts.
Wait for an agent to finish
kaval-tui wait <id> --until <cond> blocks until a terminal’s raw output meets a condition, then exits.
--until idle:<ms>resolves once no output byte has arrived for<ms>, which means the turn ended or the agent is awaiting you.--until match:<regex>resolves once new output matches, such as a completion marker or a returned-prompt sentinel.--timeoutfails loud (exit 2), so a wedged agent cannot hang the loop. A terminal that exits first exits 3.- It is keyed on raw PTY bytes, so it needs no shell hooks and works for any terminal.
padi-tui waitreads real agent state off padi instead.
Detach from a terminal
While you are attached, nothing is intercepted except a ~ typed at the start of a line (right after Enter, and the start of the session counts). Mid-line tildes, every Ctrl chord and pasted text pass straight through, so the program inside never loses a key.
| Escape | What it does |
|---|---|
~. | detach — kaval-tui exits, the daemon keeps the terminal; re-attach anytime |
~~ | send one literal ~ to the shell |
~? | show this escape help |
# ~ clashes (nested ssh?) — rebind it:
kaval-tui attach <id> --escape %
Detach is client-side: kaval-tui can come and go while the daemon holds the terminal. Restarting the daemon itself ends its terminals.
Sockets and limits
- A standalone kaval’s socket lives at
$XDG_RUNTIME_DIR/kaval/pty-host.sock, or at/tmp/kaval-$UID/pty-host.sockwhen$XDG_RUNTIME_DIRis unset. It appears when the daemon boots. - A kolu’s kaval is spawned by its
padiand named by a digest of padi’s state-root, at$XDG_RUNTIME_DIR/kaval-<digest>/pty-host.sock, so two kolus on one machine never collide. --socketgoes after the subcommand (kaval-tui list --socket …), and you need it only to choose between daemons.- Discovery reads one of those two directories, the one your own environment puts you in. A shell with
$XDG_RUNTIME_DIRset does not list a daemon bound under/tmp, and the reverse holds too. - When the program inside a terminal exits, kaval-tui exits with the same code. An unreachable daemon is a one-line error, never a hang.
- kaval cannot drain: draining would destroy the live PTYs it exists to preserve, so a drain call is refused with a typed error. An old build keeps running, with an update nudge.
- Operations covers stopping a daemon by hand. The full design is in the kaval atlas note.