kolu is a terminal app built for scale: real xterm.js tiles on an infinite 2D canvas, with a dock that never loses one — for claude, codex, opencode, or anything you run in a shell, especially many at once.

Unlike agent command centers that wrap a single model behind their own chat UI, kolu stays out of the agent's way: the terminal is the universal interface, so claude, opencode, or whatever ships next week works out of the box — and you can drop to a plain shell whenever you want. Kolu treats terminals as the thesis, not the substrate.

Two principles shape what kolu is and isn't:

Agent-agnostic. The terminal is the universal interface. Kolu doesn't wrap a specific model or lock you into one CLI — claude, opencode, or whatever ships next week all work the same way, because they're just programs you run in a shell. There's no agent registry to update, no adapter to write, no vendor lock-in. Any new agent CLI picks up first-class features automatically: run it once in any kolu terminal and the next time you create a worktree, it appears in the sub-palette as a launch option — no configuration, no per-agent code. You can always drop to a plain shell without leaving the app.

Auto-detected, zero setup. Kolu populates its UI by watching what you already do — the repos you cd into, the agents you run, the sessions you save — not by asking you to configure it. Recent repos track cd events, branch / PR / CI status derive from the terminal's CWD, Claude Code state is read from the foreground pid, and recent agent CLIs come from preexec command marks emitted by kolu's shell integration. If kolu knows something, it's because the shell already told it. The surface grows with your workflow, not with a preferences pane.

Install Nix and then run:

The same command runs kolu and updates it — --refresh busts Nix's flake cache so you always pull the latest commit:

nix --refresh run github:juspay/kolu       # serve on 127.0.0.1:7681
nix --refresh run github:juspay/kolu -- --host 0.0.0.0 --port 8080  # expose on LAN

Open http://127.0.0.1:7681 (or the address you chose above).

• Create, switch, and kill terminals — every terminal renders as a draggable tile on the canvas, with the left-edge dock as the canonical at-a-glance navigator (rail / cards levels) and the command palette as the canonical search surface
• Sleep & wake — put a terminal you're done with for now to sleep (the ☾ button on its title bar, or the Sleep terminal command): its PTY, agent process, and GPU/WebGL context are released — exactly as if closed — while the tile stays on the canvas, moonlit and dormant, showing the last-known directory · branch · PR it was working. Wake re-spawns it in the same directory and resumes the agent right where it left off — the same restore path a server reboot runs, so the conversation returns, not a blank shell. A sleeping tile stays a full canvas citizen (drag / resize / rename / re-theme; only typing is fenced off), survives a full restart, reads moonlit in the dock and minimap, and closing one discards it rather than killing a process (nothing is running to end)
• Split terminals — Ctrl+` splits a bottom pane per terminal; Ctrl+Shift+` adds tabs, Ctrl+PageDown / Ctrl+PageUp cycles. Open splits surface as an inline ▭ N chip on the parent's dock row so the count is visible at a glance, not just on the active tile's title bar
• Font zoom (Cmd/Ctrl +/-), persisted per terminal across sessions
• WebGL rendering with canvas fallback, clickable URLs, Unicode 11, inline images (sixel, iTerm2, kitty)
• Clickable file references — terminal output that contains path/to/file.ts:42 (with optional :col or -end line range) is linkified; clicking opens the file in the right panel's Code tab at that line. A folder path (packages/client/, or any slash path naming a directory) linkifies too — clicking it reveals that folder in the Code tab's All-files tree (expanded and scrolled into view) rather than opening a file, and a real directory wins over a same-named file elsewhere
• The right panel opens by default on desktop for new users, landing on the Code tab's All files repo browser — an editor-like (Zed/VSCode) first surface that always has a populated tree, rather than a diff view that reads empty on a clean tree. Code leads the tab row; toggle the whole panel with the chrome-bar inspector button or Cmd/Ctrl+Alt+B. The open/collapsed state, active tab, and code mode all persist, so anyone who tunes them keeps their choice. (On mobile the panel hosts as a bottom drawer that stays closed until you tap the chrome-sheet inspector toggle — but it still defaults to the same Code / All-files surface once opened.)
• Lazy attach — late-joining clients receive serialized screen state (~4KB) instead of replaying raw buffer
• Mobile key bar — on coarse-pointer devices, a two-row bar above the terminal sends the keys soft keyboards lack (Esc, Tab, arrows, Ctrl+C) plus an IME-bypassing Enter for Android chat keyboards, with a haptic tick on every tap. The twelve soft keys lay out in a six-column grid — two rows of six — so every key is visible at once, with no horizontal scrolling. Two sticky modifiers (Ctrl, Alt) arm one-shot: tap to arm, then the next character — typed on the soft keyboard or sent from the bar — folds into the chord (e.g. Ctrl+R, Alt+F) and disarms. Touch-swipe inside the terminal scrolls the scrollback buffer

• Command palette (Cmd/Ctrl+K) — search terminals, switch themes, run actions
• Worktree-naming flow — drilling into New terminal → <recent repo> opens a leaf with the worktree name pre-filled (random ADJ-NOUN, auto-selected) and an agent picker below; type a custom name and hit Enter to land in a freshly-branched worktree, or pick an agent to launch it in one step. The typed name becomes the branch name and surfaces verbatim on the dock row, so worktrees stay identifiable at a glance
• Agent-aware command palette — once you've run a known agent CLI (claude, aider, opencode, codex, goose, gemini, cursor-agent) in any kolu terminal, it surfaces in two places: as a row in the worktree-naming leaf above (so the same Enter creates the worktree and launches the agent), and as the root-level Recent agents group under the Active Terminal section as a prefill-into-active-terminal affordance. Prompt/message flag values (-p/--prompt/-m/--message) are stripped before storage so ephemeral prompt text never lands in the persisted MRU
• Dock pings — when an agent finishes in the background with an unread completion, the dock row's status indicator gains a small amber pulsing badge in its corner so you can spot it without panning, the state core staying fully visible rather than being replaced by a loud disk. Once you activate the row the badge clears — the indicator falls back to its plain state core (a quiet dim dot if the agent's still technically awaiting, or whatever its current bucket says) — so a row you've already glanced at doesn't keep yanking the eye. A simultaneous toast names the terminal that finished and carries a Switch action that pans the canvas to it; when kolu is in the background (a hidden tab or an installed PWA window that isn't focused) an OS notification does the same on click. Ctrl+Tab (or Alt+Tab) cycles terminals in MRU order: hold the modifier, press Tab to advance, release to commit
• Keyboard-driven — Cmd+T new terminal, Cmd+1…Cmd+9 jump, Cmd+Shift+[ / Cmd+Shift+] cycle, Cmd+Shift+M maximize, Cmd+/ shortcuts help

The desktop workspace is mode-less — every terminal renders as a draggable, resizable tile on an infinite 2D canvas. Per-terminal chrome (theme pill, agent indicator, screenshot, split toggle, find) lives on each tile's title bar. A transparent chrome bar floats at the top carrying logo, a compact identity rail (a Kolu chip with the app/server connection dot and server version, plus tooltip/dialog details for server commit, browser commit, and memory; a Kaval chip with the daemon health dot and wire contract version, plus tooltip/dialog details for uptime, memory, socket path, daemon commit, and a GitHub link. The rail still shows ≠ srv when a cached browser bundle differs from the fresh server and ⬆ update when the running daemon is behind the daemon this server would spawn), command palette, settings, and the maximize / dock / inspector toggles; the canvas grid reads through it. The left edge hosts the dock — the canonical live-terminal navigator. When the inspector panel opens, the chrome bar shrinks its right edge to the panel's left so the controls cluster stops short of the panel. When a tile is maximized, the chrome bar docks above and the dock renders as a flush left sidebar so the maximized terminal reflows next to it.

• Infinite pan & zoom — two-finger scroll / trackpad to pan, pinch or Ctrl+scroll to zoom. Hold Shift to force pan even with the cursor over a terminal tile (hand-tool style). No boundaries — the canvas extends freely in every direction via CSS transform: translate() scale() (Figma/Excalidraw model)

• Snap-to-grid — tiles snap to a 24px grid on drag and resize for tidy layouts

• Double-click to create — double-click an empty spot on the canvas to open the command palette pre-drilled into the "New terminal" group, the same surface the dock's + reaches. A double-click that lands on a tile (its title bar maximizes) or the minimap is left alone — only the bare surface spawns a terminal

• Maximize a tile — double-click any tile's title bar (or click the maximize button on the tile, or the maximize toggle in the chrome bar, or press Cmd+Shift+M, or run "Maximize terminal" from the command palette) to fill the viewport; the maximized posture persists across reload via localStorage so you land back where you left off

• Dock — two-level navigator — the left-edge dock is the canonical live-terminal surface, with two progressive levels of detail (#903):

  • Rail — a 44 px-wide strip of 32 px chips, one per terminal. Each chip carries two glyphs (first alpha char of the repo + the intent's lead grapheme, falling back to the first alpha char of the branch tail) so two terminals in the same repo stay distinguishable — Kf is kolu/feat-dock-bare, Kr is kolu/remote-talk, and an intent like 🛟 FLOAT/right chips as K🛟 so the recognition cue cards mode shows survives at rail width. Repo color tints the chip's bg and ring; bucket state animates the ring (breath in alert for awaiting, accent spin-glow for working); active wears a 2 px accent halo; unread shows a pulsing alert badge at the corner. Tiny tinted repo dividers between adjacent chips from different repos carry the cards-mode section-header color into the rail.
  • Cards (default) — rows grouped by repo. Each repo gets a continuous repo-color spine down the section's left edge plus a faintly repo-tinted, sticky section header (uppercase name + row count) that pins to the scrollport top until the next repo's header pushes it off — so a row's repo reads at a glance and the label never slides out of view; rows below stack as indicator · branch · pips · time lines. The first-column status indicator folds three axes into one glyph. Its core shape carries the agent state — a quiet dim violet dot for awaiting that you've already seen and let linger, a hollow spinning teal ring for working, a tiny muted dot for idle, empty for none. A thin green live ring gently sweeps around the core while the terminal is moving bytes (a compile, a tail -f, an agent printing tokens — any output, agent or not), and a small amber unread badge appears in the corner for a needs-attention ping (an unread fresh background transition) — a badge, not a ring, so it never compounds with the live ring into nested circles, and the state core stays fully visible. The old separate live-activity dot folds into the ring (one indicator, dead left margin reclaimed). The violet "your turn" hue sits deliberately outside the warm/pending family (the CI-checks pip stays amber, as does the unread badge) so an agent waiting on you never reads as a build still churning. Different shapes (not just different colors) so the distinction survives reduced color sensitivity and peripheral glance. The same indicator's core now also leads the terminal title bar's branch/intent line (beside the same intent context it sits next to on the dock row) — tracking the live agent state (spinning ring = working, dot = awaiting), gaining the unread badge when a background ping is pending, and, like the title's agent-kind indicator, showing nothing once no agent is attached — and labels each agent-state column header in the workspace switcher. One shape vocabulary, reused verbatim, so a working or awaiting agent reads identically across dock, title, and switcher; the dock's extra idle/parked triage states (which fold in recency/staleness) stay dock-only. Agent kind (Claude / Codex / OpenCode) is not surfaced on the dock row — that identity lives on the terminal title bar where there's room. PR pip is a link to the PR with the live checks verdict + per-check list in its tooltip; the sub-terminal chip surfaces when there are nested terminals. The active row gets a quiet highlight (bg-accent/15 + 3 px accent left-edge stripe); row geometry stays constant so the dock never reflows when the active terminal changes. Pip columns share a CSS subgrid across each section, so a column whose rows all lack a pip collapses to 0 width — branch labels get every pixel the icons aren't using.

  Workspace search lives in the unified command palette (#912): the dock's search-icon button (and Cmd+Shift+K) opens the palette pre-drilled into the "Search workspaces" group. The group renders its own body inside the palette — a repo-facet sidebar plus agent-state columns (Idle, Awaiting you, Working, No agent) — each column header labelled with its agent-state pip (the spinning ring on Working, a quiet dot on Awaiting/Idle) — with the Idle column sub-grouped by age (4–12h, 12–24h, 24–48h, 48h+) the same way the minimap window picker shows it. The palette input drives an AND-token query across 20+ metadata fields; the body filters the visible cards live.

  Ordering is pure recency at every layer — the repo whose newest row just changed floats up, and within a repo the rows sort the same way. The bucket no longer promotes a row's position; "needs attention" is carried by the pip's pulse and color, not by where the row sits in the list. Rows are still clustered by branch/intent label so two terminals on the same branch stay adjacent — the cluster headline uses the same recency key, so clustering keeps siblings together without re-ordering the whole list. Click any dock row or palette workspace card to focus and center its tile. In maximized-tile mode the dock renders as an opaque flush-left sidebar and the maximized terminal reflows next to it (#904); in tiled mode the dock floats over the canvas as an equally opaque card so tiles never bleed through the seams. The dock stays mounted even on the empty canvas (desktop), where it collapses to its header so the + new-terminal button is always a click away — the first terminal never depends on knowing a keyboard shortcut.

• Activity window — hard filter, not a dim — a single per-device choice (All / 4h / 12h / 24h / 48h, default 24h) governs the dock cutoff. Rows past the window disappear from the dock entirely. In cards mode (and the mobile drawer) the dock's bottom strip carries both the disclosure and the picker inline ("6 hidden by 4h window — show all"); when nothing is parked it still reads 0 hidden by 4h window so the control stays reachable, and the "show all" shortcut surfaces only when something is actually hidden. In rail mode the 44 px strip can't hold the sentence, so it collapses to just the centered picker chip — and, when the window is actually hiding rows, a compact accent count stacked above it that doubles as the one-click "show all" recovery button (its accessible label spells out "N terminals hidden by the activity window — show all"). The minimap's matching pill drives the same shared signal (via the same ActivityWindowChip), so tightening one tightens the other. The canvas tile fades, the hidden terminal stops counting toward the OS/PWA dock badge, and any fresh agent transition surfaces it automatically.

• Minimap heatmap — the canvas minimap dots any tile whose agent is currently waiting (alert color) or thinking/tool_use (accent color), suppressed once the tile falls outside the activity window, so you can scan a 20-tile workspace for "who needs me" or "who is making progress" without opening the switcher. Tiles outside the window collapse to small ghost markers so visual weight shifts onto what's still in play.

• Tile state borders — each live tile carries its agent's run-state as motion on its own border, drawn in the tile's repo color: a working terminal runs a calm marching-ants outline, one that needs you sweeps a comet whose speed is the urgency (fastest for a fresh "your turn", slowing as the wait goes stale), and a missed background alert (a tile that flipped to needing you while you weren't looking) throbs loudest until you focus it; idle and parked tiles stay dark. The tile you're in wears a crisp repo-color outline floating just off its edge — one color throughout, so focus and state never fight over a hue — and prefers-reduced-motion collapses every aura to a static ring. It's the tile-level companion to the minimap heatmap and the dock's state pips, reading from the same upstream agent-state classifiers so the three surfaces never disagree

• Identity-collision suffix — when two terminals share the same repo+branch (or cwd, for non-git), the server assigns each a stable 4-char id suffix (#a3f2) so the dock and tile chrome can disambiguate them at a glance

• Canvas navigation — the command palette can center the active tile when panning has moved it out of view, or arrange the canvas by repo to cluster each repo's tiles into a square-ish island while preserving every tile's current size. Arranging is a one-shot, explicit action: a new terminal opens at the viewport without rearranging anything, so the tiles you've already placed stay exactly where you put them — clustering happens only when you run "Arrange canvas by repo"

• Per-tile theming — title bars and pill swatches derive their colors from each terminal's theme for guaranteed contrast

• Mobile — the canvas, pan/zoom, and the desktop dock are disabled; the active tile fills the viewport and swipe-left/right cycles between terminals in compact switcher order. Switching or revealing a tile never raises the soft keyboard — it appears only when you tap the terminal, so it stays out of the way while you navigate. A pull-down chrome sheet at the top reveals the same logo + vertical switcher list + controls as a touch-sized drawer. The right panel — Code + Inspector tabs, file tree, HTML/SVG/PDF iframe + image + video preview — hosts as a bottom drawer instead of a side split, mounting the same RightPanel → CodeTab subtree as desktop; tap the inspector toggle in the chrome sheet (or a path:line link in terminal output) to open it

• Auto-detected repo name, branch, and working directory (via OSC 7 + .git/HEAD watcher)
• GitHub PR detection — shows the merge-state icon (open / merged / closed), CI check status dot (pass/pending/fail), #N, and PR title on the tile chrome, the inspector, the dock row, and the workspace-switcher card so the merge state is visible from every navigator surface without focusing the tile
• Per-repo color coding on the dock, tile chrome, canvas tile border, and minimap via golden-angle hue spacing — the same hue echoes across every surface so a repo reads as one identity at a glance
• Git-status indicators across the Code tab's All files view — every file in the full-repo browse tree carries the same change color the Local and Branch modes show (modified / added / untracked / renamed / deleted), so you can see what's touched without leaving whole-repo browsing, and every ancestor folder of a change is tinted in the modified color (not just Pierre's faint roll-up dot) so a changed subtree reads at a glance. The decoration overlays the working-tree status (primary) on the branch-vs-base status (fallback), so an uncommitted edit wins over a change committed earlier on the branch, while a file the branch changed but you haven't touched still shows via the branch layer. The branch layer is best-effort: a repo whose origin/<default> simply isn't fetched yet falls back to the working-tree layer rather than erroring (the explicit Branch mode still surfaces that as an actionable "run git fetch" message), while a remote-less repo with no origin at all has no base to compare and degrades to an empty Branch view instead of erroring on every change tick (#1244). The folder tint rides a small shadow-root style injected into the Pierre tree, since Pierre exposes no theme variable for it
• Inline preview of agent-generated .html / .svg / .pdf artifacts — selecting one in the Code tab's browse mode renders it in a sandboxed iframe (sandbox="allow-scripts", no allow-same-origin — page scripts run in an opaque origin and can't touch Kolu's cookies/localStorage; cross-origin fetch() from inside is blocked, which is fine for static artifacts) served from a per-terminal route under the terminal's repo root. Raster images (.png / .jpg / .gif / .webp / .ico) are served by the same route but presented with a plain <img> centered on a checkerboard, so transparency reads against the dark panel — no script sandbox needed since image bytes can't execute. Video files (.mp4 / .m4v / .webm / .mov / .ogv) render in a native <video controls> element; the route answers HTTP range requests (Accept-Ranges + 206 Partial Content) so the player can seek and plays even in browsers (Safari) that refuse media a server can't range-serve. Image, video, and iframe previews all live-reload when the file changes (mtime bump on the URL) via the same fsReadFile subscription path as text. Clicking an <a> link between previewed HTML files follows through: the in-iframe @kolu/artifact-sdk reports the loaded document's path back out (the opaque-origin sandbox blocks the parent from reading it directly), so the file tree selection moves to the linked file as you navigate. An external link (one that resolves to a different host over http(s)) can't escape the allow-scripts-only sandbox on its own — target="_blank" is blocked and a plain click would replace the preview in-pane — so the in-iframe SDK traps the click and forwards the absolute URL, and the host opens it in a real browser tab (severed opener) while the preview stays put; the parent re-checks the scheme is http(s) before opening, since postMessage is reachable by any in-frame script
• Rendered Markdown with a Source ⇄ Rendered toggle — opening a .md / .markdown file in the Code tab's browse mode renders it as a reading document (via @kolu/solid-markdown), not raw source. Full GitHub-Flavored Markdown — headings (with anchor ids), tables, task lists, strikethrough, autolinks, footnotes, and > [!NOTE]-style alerts — plus the inline HTML a README leans on (<details>, <kbd>, <p align> wrappers, definition lists, figures, images), all sanitized through DOMPurify against a tight Markdown-only allowlist — scripts, inline style/class, SVG/MathML, and form controls are all stripped, so a previewed document can neither script nor restyle the app. A leading YAML front-matter block is dropped rather than rendered as a stray heading. External anchors are forced to open in a new tab with a severed opener, while in-page TOC jumps scroll within the preview without touching the app's URL; a footnote [n] marker opens its definition in a dismissible popover anchored to the marker (click/tap to open, click-outside/Escape/scroll to dismiss, a see all ↓ link drops to the bottom list which stays unchanged) instead of making you scroll to the bottom of the document and back; and a repo-relative link ([doc](docs/guide.md)) opens the target file right in the Code tab — resolved against the document's directory, GitHub-style — instead of navigating the app origin to a broken route. Obsidian-style wikilinks ([[Note]], [[Note|alias]], [[Note#heading]]) render as a distinct violet, bracketed reference and resolve pathless across the whole repo — [[Architecture]] opens Architecture.md wherever it lives (.md implied — never a same-stemmed Architecture.feature); an ambiguous basename pops a small disambiguation menu anchored to the link, a miss toasts, and the ![[…]] embed form is left inert. The styling follows the app's light/dark preference automatically (it paints with currentColor + the app's accent, so it adapts to either palette), and a repo-relative image resolves against the document's directory and loads from the per-terminal file route — degrading to a labelled chip only when it genuinely can't be resolved. A small segmented toggle in the file header flips to the syntax-highlighted source (for exact syntax, copy, or line-anchored comments) and back; rendered is the default. Markdown stays a text file on the wire (fsReadFile kind:"text") — it renders client-side from its own content, so the toggle is offered because the file has both a source and a rendered form. The same toggle host (@kolu/solid-fileview) will later light up for HTML/SVG
• Comments on any file — select text in a source file, a branch diff, a rendered HTML artifact, or the rendered Markdown preview and a floating "+ Comment" pill appears next to the selection; click it to attach a free-text note. Comments accumulate in a tray at the bottom of the Code tab across every file in the worktree's repo; "Copy to clipboard" flushes the queue as a plain Markdown list ready to paste into the agent's prompt. Anchors use the W3C TextQuoteSelector model (quote + ±32-char context), so the agent receiving the payload can re-locate the position by grep even after the file is edited. The same anchor model — and the same pure extractQuote / findQuote functions — powers every surface: the parent-side source/diff view (Pierre's CodeView), the light-DOM Markdown preview (anchored against the preview's own subtree), and the in-iframe HTML annotator served by @kolu/artifact-sdk. A comment on the rendered Markdown preview carries no source line — a rendered line isn't a source line and the quote ("Hello Doc") needn't appear verbatim in source ("# Hello Doc") — so it anchors by quote alone (still grep-locatable); a comment in the source view additionally carries a line range. Comments persist per repo via localStorage (keyed by git repoRoot, so they survive worktree switches) and render in place via the CSS Custom Highlight API where supported

Detects Claude Code sessions running in any terminal and surfaces their state on the tile's chrome and in the dock.

What we detect:

How it works: asks each terminal for its current foreground process pid via tcgetpgrp(fd) (exposed by node-pty's foregroundPid accessor), then checks whether ~/.claude/sessions/<fgpid>.json exists. If it does, that terminal is running claude-code — we tail the session's JSONL transcript to derive state from the last message. The tail is also scanned for a dynamic Workflow the agent launched (one carrying a Run ID, so it has an observable run journal) that hasn't yet reported a terminal status via a queue-operation completion; when such a run is outstanding and its journal is still observably live (written within a couple of minutes, non-terminal), a bare end-of-turn is promoted from waiting to running in background so a busy-waiting agent doesn't read as needing you. A detached Bash command or background Task/Agent is deliberately not promoted — kolu has no journal to confirm it's still alive, and its launch marker outlives the process, so reading it as working would spin the ring forever after a Claude restart. An interrupted turn (Esc) appends a trailing user entry carrying an explicit interrupt marker ([Request interrupted by user], or an errored tool_result for a mid-tool-call Esc); that marker reads as waiting (idle), not thinking — so the dock settles instead of animating a phantom spinner that persists across claude -c. Cross-platform (Linux + macOS) since tcgetpgrp is POSIX. One state the JSONL tail can't carry is awaiting_user: for AskUserQuestion / ExitPlanMode Claude's SDK buffers the assistant message in memory and flushes the transcript only after you answer (the tail reads the prior entry — often thinking, sometimes waiting); for a tool-permission gate the tool call is on disk (the tail reads tool use) but the approval decision is screen-only. kolu recovers it by scraping the rendered screen — whenever a session sits in a pollable JSONL-derived state (thinking, tool use, or waiting), the server polls that terminal's VT-resolved screen text (@xterm/headless mirror, read server-side via getScreenText, so it works for background tiles, mobile, and remote/SSH PTYs alike) on a ~1 s clock and matches a small set of framework-rendered markers (captured live from claude-code v2.1.162): AskUserQuestion's … to navigate · Esc to cancel footer (covering both the single-select and multi-select/tabbed shapes), the edit-family permission gate's full Esc to cancel · Tab to amend footer, and the other permission gates' (Bash/WebFetch/…) numbered <n>. Yes, and don't ask again for … remember-option line. Each is chrome the framework draws, not model-supplied text, so it survives option-label churn — and each is anchored on its full surrounding structure (whole footer / whole numbered option line), so neither a look-alike menu nor the bare words in ordinary output false-promote: Claude's own /fork agent list uses ↑/↓ to select ("select", not "navigate"), the /model and folder-trust pickers end in "Esc to cancel" but not via "to navigate", and the slash menu has none. The surface is deliberately a handful of high-confidence markers we grow over time; ExitPlanMode (whose prompt has no equivalent footer) and the hook-based path are follow-ups. A match promotes the active pollable state → awaiting input; when the prompt clears, the same poll republishes the raw JSONL-derived state (the JSONL watcher's change gate would otherwise silently drop the structurally-identical settle-back, so the watcher itself can't demote it — the poll self-demotes instead). The signature is pure and centralized in claude-code/src/screen.ts, and the scrape is just another source for the already-wired awaiting_user state — no client change. Each card also surfaces the session's display title (custom title › auto-generated summary › first prompt) via the Claude Agent SDK's getSessionInfo(), refreshed best-effort on each transcript change. The tile chrome also shows a running token count (compact, e.g. 47K) summed from the latest assistant entry's message.usage — input_tokens + cache_creation_input_tokens + cache_read_input_tokens. Raw count only; window size isn't inferable from the JSONL (1M beta strips its suffix, so a % would lie), and the raw number is the useful signal anyway.

What we can't detect:

• ExitPlanMode (plan-approval) — AskUserQuestion and the tool-permission gates are surfaced as awaiting input (via the screen scrape above, #905), but the plan-approval dialog has a distinct on-screen shape (Ready to code?, no arrow-nav footer) and would need its own, more volatile literal added to screen.ts — a deliberate follow-up, kept out for now to keep the detection surface small and high-confidence
• Streaming progress — intermediate thinking tokens aren't tracked, only final state transitions
• Wrapped invocations — if claude-code is launched via a wrapper (e.g. script -q out.log claude), the foreground pid is the wrapper, not claude itself, so the session lookup misses
• Sub-agents — individual nested agent spawns aren't tracked as separate sessions. When the parent ends its turn to wait on a launched dynamic workflow, though, Kolu surfaces that workflow's fan-out — its name and live sub-agent count, read from the run journal at <session>/workflows/<runId>.json — on the tile chrome and inspector while the parent is running in background

Debugging detection: the command palette has a Debug → Show Claude transcript entry (visible only when the active terminal has a Claude session) that opens a side-by-side view of the server's state-change log next to the raw JSONL events from disk since monitoring began. Use it when state seems stuck or transitions feel missed.

Detects Codex TUI sessions and surfaces their state alongside Claude Code and OpenCode.

How it works: when the foreground process is codex, the adapter queries Codex's threads SQLite DB (highest-numbered ~/.codex/state_<N>.sqlite, auto-discovered on startup) to find the most recently updated non-archived cli thread whose cwd matches the terminal's CWD. Thread metadata (title, model) comes straight from indexed columns. The running context-token count and the agent state (thinking / tool*use / waiting) both come from tailing the per-thread rollout JSONL at threads.rollout_path: state from pattern-matching task_started / task_complete / function_call / function_call_output events, and contextTokens from reading info.last_token_usage.input_tokens on the latest token_count event — the same number Codex's own /status command displays. Live updates come from fs.watch on the SQLite WAL file (state*<N>.sqlite-wal); Codex writes the WAL and appends the JSONL in the same cycle (verified: nanosecond-identical mtimes), so one signal covers both sources.

Why last_token_usage.input_tokens alone, not a sum? Claude-code sums three input-side fields (input_tokens + cache_creation + cache_read) because Anthropic's schema makes them disjoint buckets. OpenAI's schema — which Codex emits — is different: input_tokens is already the full prompt, and cached_input_tokens is a breakdown of what portion was a cache hit, not an additional count. Adding them double-counts every cache re-read. The field as-is is what /status reports and what gives users an accurate read on context pressure.

Why not threads.tokens_used? That column holds the session-lifetime cumulative total (total_token_usage.total_tokens summed across every turn). For long-running sessions it climbs into tens of millions — misleading as "how close am I to exhausting the 258 K context window."

Why both SQLite and JSONL? SQLite alone gives us title and model cheaply from indexed columns — no file read, no parsing. JSONL alone would force re-parsing the entire file on every update to recover title. Neither source alone carries both the event stream that drives state AND the per-turn token usage AND the columns that drive metadata — combining them specializes by purpose.

What we detect:

Open-call tracking is scoped per-turn: a function_call with no matching _output that straddles a task_started boundary (user aborted a prior tool-using turn) does not pin the next turn to tool_use.

What we can't detect (yet):

• Task-progress checklist — Codex has no TodoWrite equivalent (task_started/task_complete are per-turn lifecycle, not user-visible checklists), so the taskProgress field stays permanently null
• Column-level schema changes — the filename version is auto-discovered, but if upstream renames or removes a depended-on column in the threads table (e.g. rollout_path, cwd, source, archived), session detection silently returns zero matches. Set KOLU_CODEX_DB to pin a known-good DB while a fix ships
• Same-directory disambiguation — if multiple Codex threads share a cwd, we pick the most recently updated one (same heuristic as OpenCode)
• Sub-agent threads — Codex's spawned sub-agents get source = '{"subagent":…}' rows in the same table; we filter them out (they have no foreground terminal to bind to)

Detects OpenCode sessions and shows their state alongside Claude Code on the tile chrome.

How it works: when the foreground process is opencode, the adapter queries OpenCode's SQLite database directly at ~/.local/share/opencode/opencode.db to find the most recently updated session whose directory matches the terminal's CWD. State is derived from the latest message: a user message means the assistant is thinking; an assistant message with time.completed set and finish: "stop" means waiting; otherwise still thinking. Todo progress comes from a COUNT(*) over the todo table — much simpler than Claude Code's tool-call parsing since OpenCode stores todos as first-class rows with a status column. The tile chrome also shows the running token count from the latest assistant message's tokens.total (pre-summed by OpenCode — we pass it through). Live updates come from fs.watch on the SQLite WAL file (opencode.db-wal), which OpenCode writes to on every database mutation.

Why SQLite, not REST? The OpenCode TUI doesn't expose an HTTP server by default — that's a separate opencode serve mode. Reading the SQLite DB directly works against the actual TUI users run, with no port discovery and no extra processes. SQLite WAL mode allows concurrent readers while OpenCode is writing, so we can open the DB read-only without blocking it.

What we detect:

What we can't detect (yet):

• Same-directory disambiguation — if multiple OpenCode sessions share a working directory, we pick the most recently updated one
• Non-default DB location — set KOLU_OPENCODE_DB to override the path

• 200+ color schemes from iTerm2-Color-Schemes, switchable at runtime
• Live preview while browsing themes in the palette
• New terminal theme — a new terminal either Inherits the active terminal's theme (set one theme and every new terminal follows, like new terminals inherit its size) or Shuffles a background perceptually distinct from every other open terminal (the default)
• Shuffle behaviour — which themes any shuffle draws from, a shuffled new terminal and the ⌘⇧J "shuffle this terminal" shortcut alike: Auto (match the app's light/dark mode — the default), Dark / Light (force that family), or Random (the whole catalogue)
• Dark / light / system UI theme
• Installed PWA chrome color derives from the server hostname, so app windows from different machines are easier to distinguish
• Welcome for new users — the empty canvas shows three bird's-eye moments (pin kolu as an app · reach it remotely via Tailscale · run agents), above session restore and re-openable anytime via the command palette's Tutorial command. The "pin it" card is context-aware: over plain http:// (a LAN/Tailscale IP, where browsers can't install a PWA without a secure context) it points you to the Tailscale HTTPS fix instead of a dead Install button. Full guide at kolu.dev

• Ctrl+V pastes images into any agent that accepts paste-as-file-path (Claude Code, codex, …) — the server saves the browser's clipboard image and bracketed-pastes its path into the PTY
• Drag-and-drop files onto a terminal — the file uploads to the server (10 MB cap, curated extension allowlist covering text, code, structured data, common docs, images, and video) and its path is bracketed-pasted into the PTY just like a clipboard image, so agents that accept paste-as-file-path pick it up automatically. Disallowed types and oversize drops are rejected client-side with a toast and never hit the wire

Record the Kolu tab — whole canvas or a single maximized terminal — with microphone and optional webcam PiP, straight to a local .webm file. Chromium-only (uses the File System Access API).

• One-click setup popover — mic picker with live 8-segment RMS level meter, webcam toggle + device picker + circular preview, all in a compact popover anchored to the chrome-bar record button
• Streaming to disk — chunks flow from MediaRecorder into a FileSystemWritableFileStream continuously, so memory stays flat regardless of recording length. A partial .webm survives a browser crash (recoverable with ffmpeg)
• Duration-fix pass — Chrome's MediaRecorder omits the WebM SegmentInfo.Duration header in streaming mode, which makes players show a ~1 second duration. At stop, the saved file is read back, patched via fix-webm-duration, and rewritten
• Pause / resume — ⌘⇧. toggles; the segmented recording capsule in the chrome bar shifts red → amber and the breathing halo suppresses while paused
• Webcam PiP overlay — when enabled, a circular mirrored <video> pins to the bottom-right above maximized tiles but below the chrome bar, and is baked into the recording by the tab-capture stream (no offscreen compositing)
• Browser picker collapses — getDisplayMedia({ preferCurrentTab: true, selfBrowserSurface: "include" }) turns the multi-surface picker into a single "Share this tab" confirmation

Command-palette entry "Export agent session as HTML" (visible only when the active terminal has an agent session) opens an export picker for the current Claude Code, OpenCode, or Codex transcript. Choose a lightweight chat log (Human / AI messages only), a full transcript (same design, with reasoning, tool calls, results, edits, and subtasks collapsed under native disclosure blocks), or both files. Each output is a self-contained .html file — no external assets, no server upload, opens in any browser offline.

• Vendor-neutral IR — each integration loader normalizes its session storage (Claude's JSONL, OpenCode's SQLite, Codex's rollout) into the same TranscriptEvent union in kolu-transcript-core. The renderer dispatches on event.kind, never on the agent — adding a new vendor's quirky tool name is a loader-side change with zero renderer churn
• Typed ToolInput union — every Claude Code built-in tool (34 entries: Edit/Bash/Skill/TaskCreate/WebSearch/PowerShell/…) and every OpenCode built-in tool (13 entries: edit/bash/todowrite/lsp/question/…) maps to a kind the renderer can specialise on. Anything we haven't modelled lands honestly in kind: "unknown" with the original toolName preserved — the document never lies about what a tool was
• Plain renderer with tiny prompt nav — prose still goes through marked, but fenced code, tool payloads, and patches render as escaped text. The exported document ships no custom elements and no syntax-highlighting bundle; when there is more than one human prompt, a tiny inline script powers the fixed ↑/↓ jump buttons
• One high-contrast design, two depths — both files use the same conversation-ledger layout: patterned page background, strong role colours, hard borders, dark code blocks, and previous/next human-message navigation. The difference is serialization: chat mode omits non-conversation payloads; full mode includes them collapsed with <details> so the audit trail is available without becoming the default reading surface

pnpm monorepo:

All browser traffic flows over a single WebSocket (/rpc/ws) via oRPC. The contract in packages/common/ is shared by both sides — types checked at compile time, payloads validated by Zod at runtime. (The CLI client kaval-tui is the exception: it reaches the kaval daemon over its local unix socket speaking the ptyHostSurface contract — same oRPC framing, a different transport. The server reaches that same socket; both are clients of the daemon. See the kaval-tui row above.) That RPC surface is unauthenticated, so a same-origin gate (@kolu/surface/ws-origin, the CSWSH sibling of gateStaleSocket) runs before oRPC on both browser-reachable paths: gateWsOrigin rejects a cross-site Origin at the /rpc/ws upgrade, and gateHttpRpcOrigin 403s a cross-site call to the mounted /rpc/* HTTP handler (a multipart/form-data POST needs no CORS preflight, so the socket gate alone wouldn't cover it). Loopback binding doesn't defend this — the attacker page runs in the operator's own browser; a reverse-proxy / tailscale serve front-end whose origin differs from the forwarded Host is allowlisted via KOLU_ALLOWED_ORIGINS. Two communication patterns:

Subscriptions use createSubscription — a ~150-line primitive that converts an AsyncIterable into a SolidJS signal via createStore + reconcile for fine-grained reactivity; the client consumes it through @kolu/surface's hooks (useCell / useCollection / useStream / useEvent) rather than directly. Per-terminal subscriptions use SolidJS's mapArray for automatic lifecycle management.

Two loops drive the system — a terminal I/O loop (the hot path) and a metadata loop (side-channel enrichment). Both flow over the same WebSocket and land in SolidJS signals on the client via createSubscription.

flowchart TB
  subgraph Client["Client (SolidJS)"]
    User((User)):::user
    Xterm["xterm.js\nrender + input"]:::client
    Subs["createSubscription\nsignals"]:::cache
    UI["UI components\ndock · tile chrome · chrome bar · palette"]:::client
  end

  subgraph Server["Server (Hono)"]
    subgraph PtyHost["kaval (a daemon kolu spawns; ssh later — same ptyHostSurface contract)"]
      Host["node-pty + @xterm/headless mirror\n+ VT taps"]:::server
    end
    Sensors["Sensor set\ngit · PR · agent-detect\n(runs in kolu-server)"]:::server
    Backend["LocalTerminalEndpoint\nauthored + awareness · activity · sessions"]:::server
  end

  %% Terminal I/O loop (through the ptyHostSurface contract)
  User -->|"keystroke"| Xterm
  Xterm -->|"sendInput\n(request/response)"| Host
  Host -->|"attach stream\n(snapshot + deltas)"| Xterm

  %% Metadata loop
  Host -.->|"tap streams\n(cwd · title · cmd · foreground)"| Sensors
  Host -.->|"inventory feed\n(created · exited → adopt)"| Backend
  Sensors -.->|"metadata + activity\n(direct writes)"| Backend
  Backend -.->|"metadata · activity · terminal-list\n(subscriptions)"| Subs
  Subs -.-> UI

  %% User actions
  UI -->|"create · kill · reorder\n(request/response)"| Backend

  classDef user fill:#f4a261,stroke:#e76f51,color:#000
  classDef client fill:#2a9d8f,stroke:#264653,color:#fff
  classDef cache fill:#e76f51,stroke:#f4a261,color:#fff
  classDef server fill:#264653,stroke:#2a9d8f,color:#fff

  style Client fill:none,stroke:#2a9d8f,stroke-width:2px,color:#2a9d8f
  style Server fill:none,stroke:#264653,stroke-width:2px,color:#264653
  style PtyHost fill:none,stroke:#e9c46a,stroke-width:1px,color:#264653

Terminal I/O (solid lines) — keystrokes go through sendInput RPC to the PTY owned by kaval, which kolu-server drives over the ptyHostSurface contract; shell output flows back as an attach stream — a screen-state snapshot followed by the live delta stream, partitioned race-free at a single point so nothing is lost or double-painted — to xterm.js. The host's @xterm/headless mirror parses VT sequences server-side for those snapshots¹, and fans the output out to every attached client through a bounded Channel.

Metadata (dashed lines) — every per-terminal observer lives in the memoryless awareness producer at @kolu/terminal-workspace — a standalone package lifted out of kolu-server (P1a of the pulam plan) so the standalone pulam daemon (P1c — packages/pulam/) reuses the same producer code, parameterized over SensorSignals + an emit callback so the host is the only thing that varies (its lone host coupling, a logger, is injected as a startSensors parameter). kolu-server still runs it in-process for local terminals (LocalTerminalEndpoint, the concrete TerminalEndpoint for "this kolu process"), fed kaval's raw VT taps over the ptyHostSurface contract — a unix-socket link to the spawned daemon (unixSocketLink/stdioLink framing), held behind a stable forwarding facade so the consumer code is unchanged from the in-process era and a future ssh transport swaps only the link. The endpoint hands the producer only the inputs it observes — {pid, cwd, signals, …}, never a PtyHandle, so the producer has zero synchronous dependency on the host (the live foreground reads it once read off the handle now arrive on a foreground tap) — calls startSensors, and folds each emitted TerminalEvent into kolu's stored TerminalState (the local watch loop gates recency BY VALUE — it compares each re-resolved agent identity against the saved restore target, so an adopt / resuming-wake of the same session keeps its saved recency, with no wall-clock window). The fold commits the snapshot half onto the snapshots collection and the two remembered facts (+ the fold-derived discriminated restoreTarget) onto the authored record + the activity feed. The terminals:dirty autosave arms ONLY on a restore-relevant value change (restoreRelevantEqual — cwd · git · pr + the remembered facts), so the ~150 ms agent / foreground firehose folds to an equal projection and never reaches disk. The old persisted/live write-fence is gone: a memoryless producer's TerminalSnapshot cannot spell a memory fact, so the fence is now the emit type, not a narrowed updateServerMetadata mutator. Decoupling the producer from the handle — reading taps, not a PtyHandle — is what lets it run unchanged whether pty-host is in-process, behind a socket, or on an ssh host; Local- and RemoteTerminalEndpoint then differ only in which transport builds the pty-host client. The producer's sensors themselves: CWD changes (OSC 7) → git sensor (.git/HEAD watcher for branch identity + a shared .git/config watcher so a git remote set-url re-resolves GitInfo.remoteUrl without a branch switch — both refcounted shared singletons that collapse a repo's worktrees onto one OS handle) → PR sensor (anyforge's subscribePr poll loop, re-resolving on any repoRoot/branch/remoteUrl change). The kernel still names no forge: a small dispatching ForgeAdapter in @kolu/terminal-workspace (sensors.ts) maps the remote's host (via anyforge's parseRemoteHost) to a forge through a FORGE_ADAPTERS/detectForge seam and routes each resolve there. Only github.com resolves to the gh adapter from kolu-github; every other remote (Codeberg, a self-hosted forge, an unknown host, or none) maps to an unsupported arm that resolves to the honest unsupported PrResult without ever spawning gh — a non-GitHub remote can't have a GitHub PR, so asking gh would only produce log noise (kolu#1627). kolu doesn't guess that an arbitrary clone URL is GitHub, so a GitHub Enterprise remote is out of scope (no PR pill) until per-host config lands. A real second forge adds a FORGE_ADAPTERS entry and a detectForge arm, kolu#1240. Agent detection uses a single generic orchestrator (startAgentSensor in @kolu/terminal-workspace's sensors.ts) driven by per-agent AgentAdapter instances from each integration package. Today three instances are registered: claudeCodeAdapter (from kolu-claude-code) wakes on title events (OSC 2) and its own fs.watch on ~/.claude/sessions/; codexAdapter (from kolu-codex) queries the highest-numbered ~/.codex/state_<N>.sqlite for thread metadata and tails the matched rollout JSONL for state transitions; opencodeAdapter (from kolu-opencode) queries OpenCode's SQLite database directly and watches its WAL file for live state updates. Adding a new agent CLI is one new AgentAdapter and one line in startSensors — no server-side adapter file. All the producer's sensors emit observations; kolu's fold (relocated into @kolu/padi by W1.M) reduces the stream, and padi composes the authored ⋈ snapshot halves server-side (composeTerminalMetadata) and serves the one per-terminal record on padiSurface's terminals collection — the client reads that composed record directly, with no client-side join². kolu-server still publishes the generic snapshot half on terminalWorkspaceSurface.snapshots for the awareness surface (pulam parity). Separately, kolu's preexec hook emits an OSC 633;E command mark before each user command; kaval surfaces it on its command-run tap, the endpoint bridges that onto a per-terminal commandRun channel, and the agent-command tracker (in @kolu/terminal-workspace) matches the first token against a known-agents allowlist and emits a commandRun observation (flagged replayed for a late-join replay). kolu's fold keeps the latest recognized command as the lastAgentCommand memory; the watch loop bumps kolu-server's bounded recent-agents MRU (only on a non-replayed mark) for the agent-aware command palette; and the producer's own shared working state stashes the recognized basename, so codex/opencode session detection still matches when the agent is an interpreter shim (e.g. npm-installed codex, whose kernel-level process name is node). No /proc lookups or argv scraping. The TerminalEndpoint interface itself lives in kolu-common/terminalEndpoint — LocalTerminalEndpoint is the one concrete shape today; a future RemoteTerminalEndpoint (for terminals running on SSH hosts) is the seam's second impl, and call sites depend on the interface, not on which kind they hold.

User actions — the unified command palette (Cmd+K for commands; Cmd+Shift+K or the dock's search-icon button to drill into "Search workspaces") and tile chrome dispatch plain oRPC client calls (useTerminalCrud, useWorktreeOps). The server's live subscriptions push updated state to the client automatically. useTerminalMetadata uses SolidJS's mapArray to create per-terminal subscriptions that automatically tear down when terminals are removed³.

Persistence — sessions auto-save to ~/.config/kolu/state.json via conf, debounced at 500 ms⁴.

PartySocket handles WebSocket auto-reconnect; @kolu/surface/solid's surfaceClient (wired up in packages/client/src/wire.ts) installs oRPC's ClientRetryPlugin so every Cell/Collection/Stream/Event hook (and the unenrolledStreamCall escape hatch for raw streams like terminal attach) transparently re-subscribes after a drop — every server-side streaming handler is already snapshot-then-deltas and the framework's Cell/Collection/Stream hooks own the snapshot-replace / delta-reconcile — e.g. useTerminalMetadata.ts joins the kolu.authored and terminalWorkspace.snapshots collections, each reconciled by the framework — so re-subscribe resume is structural, not defensive. That re-subscribe only fires on an observed drop, though — and PartySocket ships no keepalive, so a silently half-open socket (the TCP died with no FIN/RST — a client's laptop slept, Wi-Fi roamed, or a NAT/proxy evicted the idle connection) would fire neither close nor error: the socket sits OPEN, every stream iterator hangs with nothing to retry on, and the UI freezes until a manual reload. A heartbeat closes that gap on both ends. The client watchdog — @kolu/surface-app's createHeartbeat, wired once in rpc.ts — re-uses the identity.info probe as a keep-alive on a 15s interval and, when a probe goes unanswered within 10s, forces ws.reconnect() (close code 1000, not the stale-tab 4001, so the retire path is untouched) so the existing lifecycle-disconnected → fresh-open → re-subscribe recovery takes over. kolu derives its own lifecycle so it wires the watchdog by hand; a consumer that lets <SurfaceAppProvider> own the socket (the turnkey { ws, probe } source — drishti's control-plane socket) gets the same watchdog automatically, started beside the provider's existing stale-restart retire, so it inherits the fix on a version bump with no extra wiring. The server reaper — startWsHeartbeat (@kolu/surface-app/server, the liveness twin of gateStaleSocket, typed over a structural HeartbeatableSocket so surface-app needn't depend on ws) — pings accepted sockets every 30s and terminate()s any that stop ponging, freeing the server-side zombie (and its per-terminal subscriptions) the same half-open client would otherwise leak; stale tabs the gate closes before upgrade never enrol, so #1231's protection is untouched. Both halves of the heartbeat now live in surface-app, so the second consumer (drishti) inherits the reaper instead of re-rolling it. The whole "app shell around the live wire" — delivery, build skew, the connection lifecycle, and the service-worker lifecycle (retirement, or the fetch-less notification worker) — is now owned by @kolu/surface-app, the companion to @kolu/surface; kolu serves it as a sibling surface rather than re-deriving its property (re-derived four times across PRs before it was extracted — the saga in docs/cache-bug.md). surface-app is a complete surface (a buildInfo cell + an identity.info restart probe), so kolu multiplexes four independent surfaces over the one transport with implementSurfaces / surfaceClients / composeSurfaceContracts (@kolu/surface): kolu's OWN primitives under the kolu key (surface.kolu.*), surface-app's under the surfaceApp key (surface.surfaceApp.*), the generic @kolu/terminal-workspace surface (the per-terminal snapshots collection + version cell + activity flow + fs/git) under the terminalWorkspace key (surface.terminalWorkspace.*), and @kolu/padi's padiSurface under the padi key (surface.padi.* — the composed terminals record, daemonStatus, status.expectedKaval, and the terminal lifecycle/chrome/fs/git/session procedures), each namespaced so their channels never collide. packages/client/src/wire.ts builds one surfaceClient per sibling — app (kolu's primitives, the app.cells/collections/streams/events.*.use(...) hooks), surfaceApp (the control plane), workspace (the generic terminalWorkspace surface, still served for pulam parity), and padi (kolu's primary terminal-record source after W1.R — the composed terminals collection, daemonStatus, status, and every lifecycle/chrome/fs/git/session procedure via padiRpc(padi)). On the client, packages/client/src/index.tsx wraps the app in <SurfaceAppProvider> (fed the surfaceApp sibling client as its control plane, the build commit via shellCommit() — read off the no-store shell global the build injected, never a hashed-asset define; see the freshness note below — kolu's extended koluBuildInfo fragment, and the shared status accessor from packages/client/src/rpc/rpc.ts — not a PartySocket + probe pair, so the provider reads the one lifecycle the rest of the UI already derives instead of attaching a second listener/probe); UI reads the headless useSurfaceApp() model and renders kolu's own tailwind chrome (IdentityRail, StaleBadge, TransportOverlay, the mobile sheet). The connection lifecycle is derived in-library by createServerLifecycle, invoked once in rpc.ts — that module is now just the thin module-level signal layer (lifecycle / status / serverProcessId) over it, wired to PartySocket + the serverIdentity probe once. Transport events (connecting / connected / disconnected / reconnected / restarted) stay a single ServerLifecycleEvent. A restart gets a dedicated fast path so a stale tab can't storm the new instance — and the whole handshake is @kolu/surface-app's, not kolu's (the second consumer, drishti, runs the identical partysocket+oRPC stack and inherits it): the server mints a fresh processId per boot, the client echoes its last-known one as a pid query param on every (re)connect (SERVER_PROCESS_ID_PARAM, fed by createServerLifecycle's onProcessId hook into surface-app's createProcessIdEcho — the echo and the new PartySocket(...) are built by createSurfaceSocket from @kolu/surface-app/connect, so wire.ts no longer hand-rolls the URL thunk), and the server rejects a mismatched tab at the WebSocket handshake — surface-app's gateStaleSocket (@kolu/surface-app/server) installs the error handler in the one crash-free order, lets runtime-free rejectStaleProcess(claimedPid, liveId) decide, and closes a stale tab with STALE_PROCESS_CLOSE_CODE (4001) before oRPC upgrades the socket, so the tab's dead-terminal subscriptions (attach / terminalExit / terminalMetadata) never replay against terminals the new process doesn't have and storm its logs with NOT_FOUND. The gate compares against the id surface-app's serverIdentity() exposes — the same one identity.info reports — so it can't mint a second id the client never saw. createServerLifecycle reads the close code as a definitive restarted (no probe can run — the socket is already gone) and fires its onStaleRestart callback at that single decode site; kolu's rpc.ts wires that callback to surface-app's retireSocket(ws) (stop reconnect + a throwing send so oRPC's ClientPeer rejects rather than the offline buffer growing) so the "App updated" overlay is the single path forward instead of a reconnect loop that re-presents the same dead id. TransportOverlay renders one dim-backdrop card (pointer-events-none, so users can still scroll and read buffers underneath): down shows "Reconnecting…". kolu deliberately uses no caching service worker — it can't work offline (no live WebSocket means no app), content-hashed assets are already immutable-cached by the HTTP cache, and a precaching worker only ever served stale builds across deploys. Freshness is structural at the HTTP layer, served by surface-app's installFreshStatic (packages/server/src/index.ts): the SPA shell (index.html) is no-store and every hashed asset immutable, so the one document that names the bundle is always re-fetched and a normal reload can never replay a stale shell. The build commit rides that no-store shell (window.__SURFACE_APP_COMMIT__, injected by the surfaceApp() Vite plugin; kolu's Nix koluStamped seds it into index.html only) — never a bundler define inside a hashed /assets/* file: a commit baked into an immutable-cached bundle survives a stamp-only deploy (the filename doesn't change, so the year-cached bytes don't either), pinning every returning browser on the old stamp and looping the "App updated" card forever — the bug fixed in kolu#1319 by moving identity to the always-fresh shell. TransportOverlay's "App updated" card is driven by the model — status() === "restarted" (a server restart, transient) or stale() (the durable signal that the running bundle's commit differs from the server's, the comparison behind the chrome bar's ≠ srv badge, surfaced on desktop and mobile) — and its Reload button is surface-app's reload(), a plain location.reload() that always lands on the fresh bundle. kolu does register one worker — a fetch-less notification worker (NOTIFICATION_SW_SOURCE, served at /sw.js via installFreshStatic({ serviceWorker: "notify" }), registered by registerServiceWorker() in index.tsx): an installed PWA can only raise an OS notification through ServiceWorkerRegistration.showNotification() — the page-level new Notification() constructor is an illegal constructor in standalone display mode, so it silently threw and no banner showed on macOS. Because that worker has no fetch handler it never caches, so the freshness contract still holds structurally; registering it at the / scope also replaces (and so retires) any legacy caching worker an earlier Workbox build left, which it purges on activate. kolu extends surface-app's build identity: its buildInfo cell carries not just the server commit but the kaval daemon's identity (koluBuildInfo in packages/common/src/surface.ts), which fills the commit + closure-hash of the kaval column of the identity rail (its live health dot and uptime come separately from the daemonStatus collection the supervisor publishes).

Packaged with Nix. The flake has zero inputs — nixpkgs and other sources are pinned via npins and imported with fetchTarball to keep nix develop fast (~2.6 s cold). Shared env vars are defined once in koluEnv and consumed by both the build and the devShell⁵.

Requires Nix with flakes enabled.

nix develop     # enter devshell
just dev        # run server + client with hot reload (fixed 7681/5173)
just dev-auto   # same, but on two random free ports — for a second instance
just test       # e2e tests (full nix build)

just dev-auto is the safe way to run a second kolu (or to drive one from an agent) without colliding with an instance already holding the default ports; agents capturing evidence launch via the dev-server skill.

Bug fixes, build/CI fixes, doc tweaks, and behavior-preserving refactors are welcome as direct PRs. New user-facing features need a merged proposal first — an Atlas note in the right category with status: proposed. See CONTRIBUTING.md for the full split and the proposal frontmatter.

The pipeline (defined in ci/mod.just) is driven by odu — the CI runner that grew up here, replaced juspay/justci, and graduated to its own repo (design history: the mini-ci-vs-justci Atlas note). kolu consumes it via an npins pin (npins update odu to bump) re-exported through this repo's flake, so the nix run .#odu invocations below work unchanged. It builds all flake outputs on x86_64-linux and aarch64-darwin, runs e2e tests, boots the packaged binary against /api/health as a runtime smoke, and posts GitHub commit statuses per (recipe, platform) pair. Remote lanes run over SSH against hosts from ~/.config/odu/hosts.json (falls back to ~/.config/justci/hosts.json), and a live run is attachable: nix run .#odu -- attach paints a dashboard over the run's typed surface on .ci/odu.sock. Agents drive CI through odu's MCP server — the single entry point (mcp__odu__run to start a run, wait_for_settle / tail_log / rerun_node to watch and steer it). For the x86_64-linux lane, /do leases an idle box from a fixed pool of warm Incus containers (kolu-ci-1..8, held by ci/pu/lease.sh as a background process and pinned into the run via the MCP's hosts argument; pool managed by just ci::pool-ensure) so the build starts with a hot Nix store and concurrent PRs don't contend on the substituter; see .agency/do.md.

The DAG is shaped to keep the critical path short: e2e, smoke, and home-manager each build the one store path they need (.#koluBin, .#default, kolu-via-override) rather than depending on the full devour-flake nix node, so the ~2-min e2e suite runs concurrently with the big build instead of after it (Nix store locking dedups the shared drv). nix still runs as a gate, so typecheck/website/packaging coverage is unchanged. See docs/ci-workflow-ralph-report.md for the critical-path model.

Workspace typechecking runs as a flake check (checks.x86_64-linux.typecheck), so the all-outputs build is the type gate. Note that nix build .#default on its own does not typecheck — the client is bundled by Vite and the server runs under tsx, both transpile-only — so a green app build is not a type-proof.

Only the runner posts GitHub commit statuses; the just shortcuts below stay entirely local.

nix run .#odu -- run                  # multi-platform fanout + commit statuses (strict by default)
nix run .#odu -- run --progress json  # + live NDJSON per-node feed on stdout (for agents/tools driving CI in the background)
nix run .#odu -- attach               # attach a live dashboard to a run in progress
just ci                                          # local single-platform pipeline, no statuses
just ci::e2e                                     # one recipe, no statuses

--progress json streams one line per node transition the instant it happens ({node, recipe, platform, status, exit_code?, log?}), so a tool driving CI in the background surfaces a failing recipe immediately — while sibling lanes keep running — instead of waiting for the run to finish. This is how /do reacts to failures fast; see .agency/do.md.

A home-manager module runs kolu as a systemd user service on Linux and as a launchd LaunchAgent on macOS:

{
  imports = [ kolu.homeManagerModules.default ];
  services.kolu = {
    enable = true;
    package = kolu.packages.${system}.default;
    host = "127.0.0.1"; # default
    port = 7681;         # default
  };
}

See nix/home/example/ for a full configuration — a NixOS VM test exercises the systemd path on Linux, and a standalone home-manager activation build exercises the launchd path on Darwin.

kolu's RPC surface is unauthenticated and same-origin-gated on both transports (see Communication above), so it serves only its own origin out of the box. If you front it with a reverse proxy or tailscale serve whose browser origin differs from the Host kolu receives, list that origin in services.kolu.allowedOrigins (which sets the KOLU_ALLOWED_ORIGINS env var) so the browser clears the same-origin check:

services.kolu.allowedOrigins = [ "https://box.tailnet.ts.net" ];

On macOS, the LaunchAgent writes stdout to ~/Library/Logs/kolu.out.log and stderr to ~/Library/Logs/kolu.err.log, so crashes and startup failures leave service logs alongside other user logs.

If kolu grows unbounded (V8 heap climbing over hours), set services.kolu.diagnostics.dir to an absolute path. Each restart gets its own timestamped subdir there, with a baseline heap snapshot at T+5min, periodic "diag" stats lines (memory bands + terminals/publisherSize/claudeSessions/pendingSummaryFetches), and automatic near-OOM snapshots via V8's --heapsnapshot-near-heap-limit. kill -USR2 <pid> captures an on-demand snapshot into the same dir. Diff two snapshots offline with memlab to name the retainer. Unset = zero overhead; the code path is fully gated.

The marketing site and blog at https://kolu.dev live in website/ — Astro + Tailwind, its own zero-input flake, deployed to GitHub Pages via .github/workflows/pages.yml.

just website::dev          # live preview with HMR
just website::nix-build    # reproducible build

See website/README.md for authoring posts and deploy details.

Named after கோலு, the tradition of arranging figures on tiered steps.