the kolu atlas
The Atlas.
kolu's in-repo knowledge base — grouped by kind, with related notes nested
under their parents; nothing falls through unfiled.
40 notes.
seedling budding evergreen
Bugs
3 Diagnosed defects and their fix direction.
Features
23 Proposed capabilities, not yet built. - A CI runner you attach to — graduating mini-ci beyond justci Every local CI tool runs your pipeline as a batch process and leaves you log files. mini-ci inverts that — the runner is a small live server that owns the pipeline as state, and your terminal and your coding agent attach to it over plain ssh. What that buys, what it costs — and Phase 1 — shipped in PR #1252 — which replaced justci in the kolu repo itself with the new package odu (Tamil for "run"). implemented
- @kolu/surface-mcp — every surface an MCP server, honestly scoped A generic adapter that re-exposes any @kolu/surface spec to an MCP host. The 1:1 primitive→tool map is the demo; the real package is the subscribe/teardown lifecycle, the zod→JSON-Schema bridge, and the tool-selection/authz gate. Grounded in odu's hand-built mcp face — the validated, and partial, prior art. implemented
- odu-runner — a runner you can reach with nothing running Phase 0 of odu-web, owned by the runner: split serve from run so the socket outlives any single pipeline, give runs an identity a ledger can hold (repo × sha × seq × node), and decide who keeps the long-lived coordinator alive — priced against the warm pu-box pool. Everything odu-web consumes; nothing odu-web should have to build. accepted
- odu-web — the service face of odu The browser face of odu is not a tab watching one live run — it is the service layer above the runner: a run ledger that outlives coordinators, the page a commit status Details link points at, forge triggers, and a multi-repo fleet dashboard. That territory belongs to juspay/vira today, so this is also the plan for whether odu-web replaces it. Proposed in five phases, with UI prototypes. proposed
- Canvas tiles that show their state — border prototypes Five terminals on the canvas; which one needs you? Surface each session's run-state on the tile border itself — a loudness ladder ranked by attention (alert ▸ fresh-waiting ▸ working ▸ stale-waiting ▸ idle), where "waiting" cools with last-activity age via kolu's existing activity-window. Four live, animated visual languages to choose from. implemented
- Code browser preview → @kolu/solid-fileview Invent the grid, slim the house — a Source ⇄ Rendered file-view toggle built on reusable leaf packages. Markdown is the first lit toggle; HTML/SVG next.
- Dock — telling repos apart at a glance The cards-mode dock groups rows by repo, but spends its whole colour budget on a per-branch rainbow and gives repo identity one 9.6px label that scrolls away. Shipped treatment A — repo colour moved onto a left-edge spine + a sticky tinted header (PR #1379). Calming the per-branch row rainbow was prototyped alongside but deliberately NOT shipped: branch colours stay, because they still tell branches apart within a repo. implemented
- Mobile key bar — two rows, no horizontal scroll Reflow the mobile soft key bar from a single overflow-x row into two rows so every key is reachable without horizontal scrolling. Plan + layout options + test/evidence strategy. implemented
- Multi-forge PR integration — the anyforge leaf Phased plan for kolu#1240 — phase 0a ships the gh log-noise fix, phase 0b extracts the forge-neutral PR kernel (schemas · poll loop · PrProvider) into a new anyforge leaf, phase 0c pre-stages every cross-package seam a second forge crosses (remoteUrl · the server registry + detection · the lifted neutral helpers) GitHub-only and zero-behavior, so phase 1 — the Forgejo/Codeberg adapter — is a purely additive sibling package. Grounded in a structural critique of the ic4-y/kolu#1 draft. accepted
- Remote terminals over SSH The phased master plan for kolu#951 — remote terminals over SSH. The foundation is shipped — the TerminalBackend seam (R-1), the @kolu/surface framework + @kolu/surface-nix-host (R-1.5), the shared provider engine (R-1.6), and local PTY daemonization (R-4, the kaval daemon — terminals survive a deploy). What remains is the ssh transport + ChromeBar host switcher (R-2) then network-blip resilience (R-3). The end state is multi-host — 1 local + N ssh-remote kaval daemons, all surviving and reattachable, switchable from the ChromeBar. accepted
- Kaval sessions — dial daemons, multiplex the canvas A direction reframe for R-2 now kaval ships. Dial kavals as first-class endpoints — local over a unix socket, remote over ssh (provisioned via surface-nix-host) — with hosts auto-detected from ssh config. The same substrate supports either switching one kaval at a time (tmux-style) or multiplexing several on one canvas (per-tile piggybacks on its kaval); the canvas metaphor leans multiplex. First step — kaval-tui create, then --host (reach + provision in one PR). accepted
- R-4 — kaval, the standalone PTY daemon The redo plan for R-4 — local PTY daemonization, reframed: the daemon is kaval, a standalone program in the drishti/odu tradition, and kolu is its first client. One rule (package boundary = process boundary = staleKey hash), a dumb fully-specified wire, and four PRs — the spawn-policy inversion, the kaval binary + client, the door with survival off, then survival — each complete w.r.t. the hazards it opens. Carries the #1034 postmortem and its hard constraints. accepted
- @kolu/surface-daemon — one spine for kaval and odu serve kaval (the PTY daemon) and odu serve (the long-lived CI coordinator) need the identical lifecycle machinery — pid-gated entry, a unix socket that outlives clients, a contract handshake on every connect, an endpoint state machine, spawn/respawn drivers. This note names that shared spine, says what is mechanism (extract) versus policy (keep per-program), and sequences it: the daemon half is born as the package in kaval B1; the supervisor half is born as its own `@kolu/surface-daemon-supervisor` package in kaval B2 (package boundary = staleKey boundary = spine/soul line); S1 moves the handshake fragment into `@kolu/surface`; odu serve consumes the whole as the second tenant (S2). accepted
- ChromeBar identity rail (srv · client · kaval) The consolidated connection + build/commit readout in the ChromeBar. A2 shipped it as two coinciding columns (srv = server, pty = the in-process pty-host); B2 overtook that shape — renaming pty → kaval as a separate spawned daemon and adding a client-bundle column — so the live rail is three columns (srv · client · kaval). This note keeps A2's original design rationale, annotated where B2 took over. implemented
- kolu-tui — a CLI terminal client for kolu-server A terminal-side client of kolu-server's in-process pty-host — list / attach / spawn from the shell over a unix socket, no browser and no daemon. The CLI face of kolu and the seed of a tmux replacement, shipped in beta phases. accepted
- surface-connection — the WebSocket connection, owned upstream Lift the partysocket + oRPC connection assembly both kolu and drishti hand-rolled — the pid-echo, the socket construction, and the server upgrade gate — into three composable @kolu/surface-app primitives, leaving each app only its URL, socket topology, and lifecycle ownership. implemented
- The Code tab is a browser → @kolu/solid-browser The real electricity hiding in the Code tab isn't a history stack — it's the browser. Extract the location + history + link-navigation shell that drives @kolu/solid-fileview over a resolver; back/forward falls out for free, and git becomes an injected resolver. implemented
- Welcome, revamped — pin it, reach it, run agents, watch it One story across three surfaces — a bird's-eye in-app welcome, the kolu.dev home page that now carries the whole guide, and a hero demo clip filmed by the e2e harness so it can't drift from the real app. The spine — one `tailscale serve` gives kolu both the HTTPS secure context for one-click PWA install and remote reach. Plan of record + build journal. implemented
- Workflow viewer Integrating Claude Code dynamic-workflow JSONL into kolu — surfacing fan-out runs on the tile chrome and an Inspector run-list with live timelines.
Analysis
9 Investigations into how the system behaves. - App.tsx: Restore the Thin Layout Shell A plan to decompose the 785-line App.tsx kitchen-sink into six volatility-aligned seams — pressure-tested by the lowy + hickey lenses before a line of code. implemented
- Electricity — identified, and their progress A tracker for kolu's electricities — infrastructure pulled out from beneath the app into its own thing — and where each stands.
- Ghostex vs. kolu remote-terminals What Ghostex's PTY-persistence choice does and doesn't teach kolu's in-progress remote-terminals plan — one concrete borrow (honest pane⟂session state), one corroboration, one reframe; the "lean on a mux" swing doesn't survive review.
- herdr vs. kolu — what to adopt A shipped Rust agent-multiplexer (herdr) makes the same first-party-owns-the-PTYs bet kolu's remote-terminals plan chose — so it's a reference implementation of R-4 Phase B, not a competitor. One handoff-discipline borrow, several validations, two gaps the plans don't cover (native resume; resize arbitration). Claims fact-checked against both codebases.
- kaval-tui that roams — remote attach that survives the network Today kaval-tui attaches to a remote kaval over ssh stdio (TCP — it drops the moment you change networks). zmosh's idea, applied to kaval — teach kaval to also bind an encrypted-UDP listener beside its unix socket, so you attach once and keep the session through Wi-Fi↔cellular and sleep/wake, with no reconnect and no lost scrollback. No extra process; kaval already owns the hard half (server-side VT + snapshot-then-delta); only the transport changes.
- OpenCode v2 Perf — What Kolu Can Adapt OpenCode Desktop v2's "10×" is a streaming-markdown number. Mapped onto Kolu's actual surfaces, most of it has no consumer — but every technique that does has now shipped — R1 Pierre 1.2.10 + Shiki 4.2.0 (#1360), R2 the highlight worker pool (#1363), and R3+R4 the canvas-gesture p99 harness + rAF-coalesced pan/zoom. implemented
- Preferences storm Debouncing the rightPanel resize feedback loop (#1041) — Corvu's idempotent re-emits + a no-equals prefs cell cause ~200 writes/min; the fix splits apply-local-now from a coalesced, patch-space server flush. accepted
- Whole-codebase correctness review A static audit of path authority, terminal lifecycle, channel cancellation, session-restore fidelity, parser failures, and kill confirmation. Not a style review.
Reference
5 Durable knowledge — designs, decisions, how it works.