kolu
Docs

help

Common snags.

I see no one-click Install button

Open kolu over HTTPS or over localhost. The automatic Install prompt needs one of the two, and you are probably on plain http://, at a LAN IP or a Tailscale 100.x address. For the one-click prompt plus the app badge, use the https://...ts.net URL from From another device.

You can pin manually instead:

  • Chrome: menu → Save and share → Create shortcut → Open as window.
  • iOS: Share → Add to Home Screen.

The browser-by-browser rules are in Install as an App.

I am not getting desktop notifications

Check these three, in order:

  1. Secure context. Notifications ride a service worker, which needs HTTPS or localhost. From another device gives kolu a private HTTPS URL.
  2. Browser permission. Re-enable notifications from the address-bar lock icon if you dismissed the browser prompt.
  3. OS permission. On macOS, the browser and the pinned app can have separate notification entries. Allow the right one, and check Focus or Do Not Disturb.

Quick browser check:

navigator.serviceWorker
  .getRegistration()
  .then((r) => r?.showNotification("test"));

If that banner shows, the browser and OS layers are fine. kolu fires a native notification when an agent finishes in a terminal you are not watching. If you are looking at that terminal, the dock surfaces it and no banner fires. See Power Features for the multi-agent flow.

Can I use it without Tailscale?

Yes. Over localhost everything works, including one-click install, because loopback is a secure-context exemption. Tailscale matters when you want to reach kolu from another device and keep install, badge and notifications; see From another device.

Which agents does kolu support?

Run any agent. The terminal is the interface, so aider, gemini, or whatever ships next week works the moment you run it.

Seven get first-class state in the dock: claude, codex, opencode, grok (Grok Build), pi, xyne, and omp (Oh My Pi). All seven can also export the session as a self-contained HTML chat log or full transcript. Other agents run in tiles; they just do not light up the dock.

What each agent’s row can show, and how kolu reads it, is in Agent detection. For launching the first one, see First Five Minutes. For running many and exporting transcripts, see Power Features.

xyne runs but no Xyne badge lights up?

Three checks, in order:

  1. A session must exist on disk. Say at least one thing to Xyne, then look under ~/.xyne/agent/sessions/ for a directory named after your working directory with / folded to - (/home/me/proj becomes -home-me-proj), holding a <timestamp>_<uuid>.jsonl transcript. No file, no badge.
  2. Xyne must be the terminal’s foreground process, or be named by the shell’s OSC 633;E preexec hint. Running as a background job, or inside another TUI, keeps detection off.
  3. kolu only scans ~/.xyne. Point Xyne’s home elsewhere through a wrapper and detection cannot follow it. Tests and development overrides use KOLU_XYNE_DIR, which mirrors the same tree shape.

How do I update kolu?

Run the same command again:

nix --refresh run github:juspay/kolu -- web

The --refresh flag busts Nix’s flake cache so you pull the latest commit. It is the same command as in Quickstart.

A release that changes the protocol the long-lived daemons speak is a flag day, and kolu handles it for you. Daemons running from before are restarted or taken over on their own, on your machine and on each remote host over ssh. Live shells end when that happens; your session is restored from disk and agents resume their prior conversation.

A remote machine kolu cannot settle this way shows “This host runs a kolu from before the protocol change” instead of connecting. Update kolu there, or stop its padi, then reconnect.

Going backwards, to an older release, is the one direction kolu cannot do for you. Stop the daemons by hand first, with Operations → Roll back to an older release.

I closed the welcome. How do I get it back?

Open the palette with Cmd/Super + K and run Tutorial (alias: “Welcome”). It reopens the welcome overlay while you are working. The same palette opens the first terminal flow in First Five Minutes.

kolu lost my session (or my settings look wrong)

Restore from a backup: open the palette with Cmd/Super + K, go to Debug → Restore state from backup, pick the store (the server’s own, or any host’s padi), and pick a snapshot. Each row says what it holds (“14 terminals”, “preferences · 3 hosts · 4 works”), so the good snapshot is easy to spot even when the newest ones carry the corruption.

kolu keeps a short history of its own state. At every boot, and once a day while running, the server’s config store and each host’s padi session file are copied into a rotated backups/ ring beside the file, ten deep. Start fresh on the restore card copies the session file too before discarding anything, so a session thrown away on purpose comes back the same way.

Restoring a padi snapshot re-spawns its terminals beside your current ones, agents resumed and nothing killed. Restoring the server store applies live, with no restart. Your preferences, your host pool and the Conductor’s pieces of work and memory come back at once, and the running Conductor takes them rather than writing over them. Every restore snapshots the current state first, so a restore is itself undoable.

A backup does not hold two things. The Conductor’s conversation is not in it: its other half lives in the agent’s own session store, which kolu does not back up. The files a finished work kept are not either, because they are copies on disk rather than state in the config file, so a restored work whose kept files have been deleted shows them as gone.

If a snapshot cannot be taken, because the disk is full or a state directory has gone read-only, Start fresh refuses rather than discarding a session it could not copy first. Fix the disk and try again; the session is still there.

The Conductor says it cannot read one of its records

The Conductor keeps six saved records: its pieces of work, what it remembers about their terminals, its memory, where each work’s Code view was left, the conversation’s own record, and the transcript. When one of them will not read, the Conductor’s panel says so in plain words, shows what the read tripped on, and offers two buttons. You never have to edit a file, and kolu comes back without a restart.

ButtonWhat it does
Restore the newest backup that readsWalks the backup ring newest first and takes the newest snapshot this build can read, naming it. The current state is snapshotted first, so this is undoable. Not offered for the transcript.
Start with no worksStarts that record empty. The wording follows the record: no works, no remembered terminals, nothing remembered, every work’s Code view at its start, a fresh conversation, or an empty transcript. It asks you to confirm first.

A restore writes only the records the message was about, so your preferences and host pool stay as they are. The transcript is not in backups, which is why only the second button is offered for it.

Nothing is deleted either way. The value kolu could not read is kept aside as <state dir>/conductor/unreadable-<record>-<time>.json, and the confirm step names the file.

Something looks stuck, and I want to report it

Open the palette with Cmd/Super + K → Debug → Diagnostic info and click Copy diagnostics, then paste the block into your issue. The same button lives on any host tab’s status popover, behind its connection dot.

The block names:

  • every connection attempt this tab has made: when it started, whether it came up, when it ended and with what close code. An attempt that failed before it was established is recorded here and nowhere else;
  • every live subscription: what it is, when it opened, when it last heard from your machine, its update and reconnect counts. One marked parked last heard something older than the connection it rides on, the fingerprint of a tab showing stale state;
  • every host as this tab believes it, with when that belief last changed;
  • the build this tab runs, the build it talks to, and the watchdog’s last connection check.

The block is read from what the tab already holds, so it tells the truth even when the connection is what is wrong. Copy JSON beside it dumps the full per-terminal render state and the padi section’s answer, for a rendering, memory or slowness problem instead.

kolu feels slow

Ask padi, the daemon that runs your terminals on each host, what it has been doing. Open Debug → Diagnostic info in the palette and read its padi section, or run kolu surface diagnostics_read in a shell on that host. Both give the same answer, covering the last minute. The dialog asks the host whose tab is active, and Refresh asks again.

PartWhat it showsWhat a bad number means
Child processesEach kind of command padi ran, such as git status or gh pr view: how many, the time inside the start call, and how long each ran.A long start call froze padi for that long. Many runs of one kind point at whatever keeps asking.
StallsHow late padi ran work that was already due, for the last full minute and the minute in progress.A worst of a few hundred milliseconds is a freeze you feel as typing lag.
File watchersOne row per watch: its kind, folder, how many folders it covers, who asked for it, and how long it took to install.A git: working-tree row with a long install walked a large folder.
WatchesThe file watches the kernel says padi holds, for each inotify instance, on Linux.A number in the hundreds of thousands is a folder tree being watched whole.
Memorypadi’s resident memory, its JavaScript heap, and what lies outside the heap.Growth outside the heap is native memory, such as file watches.
CallsEach request padi answered: its total time, and the part spent waiting on child processes.A slow call whose time is all in children is waiting on a command, not on padi.

A request that takes longer than half a second also writes one warning line to padi’s log, naming the request, its time and its child processes.

Who asked for a watcher

AskerWho it is
terminal <id>That terminal, following the git repository it sits in.
stream subscribeRepoChangeA browser’s Code tab, following a repository.
stream subscribeFileChange (<file>)A file open in a browser’s Code tab.
stream pullRequest (branch <b>)A Conductor work following the pull request of branch <b>.
grok session detectionkolu itself, following Grok’s list of running sessions. One watch serves every terminal running grok.
git: repo-change (no subscriber; retiring within 30 s), or the same for git: file-changeNobody, for now. Whoever followed this repository or file stopped, and the watch waits 30 seconds in case they come back.

A row whose state is no-working-tree is a bare repository’s folder. kolu installs nothing there on purpose. A git: working-tree row gives no folder count, because its watcher reports none and counting would walk the folder again. The Watches line has the kernel’s count instead, for each inotify instance padi holds.

Agent session watchers, for Claude Code, pi, Xyne and Codex, have no rows. Their watches are still in the Watches count. macOS has no such count, and the line says so.

Why gh ran

Each gh pr view row says why each run happened:

CauseWhat asked
contextA terminal or a work moved to a new repository, branch or remote.
pollThe 30-second recheck of a pull request kolu already follows.
refreshThe repository changed on disk, so kolu asked again at once.

Many refresh runs mean a repository that changes all the time, such as one with a build writing into it.

kolu is using a lot of memory

Work through these three, in order:

  1. Renderer. In Settings, keep the Renderer control on Auto (the default). Auto draws recently-active tiles on the GPU and the rest with the lighter DOM renderer. DOM uses the least GPU but noticeably more system RAM. WebGL forces every tile onto the GPU and can thrash past about 16 terminals.
  2. Close or sleep what you are done with. A terminal you will not return to can be closed, or put to sleep (the ☾ button) to release its shell and GPU context while the tile stays on the canvas; see Sessions, Sleep & Wake. Disconnecting a remote host frees all of its terminals at once.
  3. Reload the tab. Memory freed by closing terminals or hosts is reclaimed immediately on a reload, and your terminals survive it: they live in the kaval daemon, not the tab.

Some growth is expected. Every terminal on the host you are viewing keeps its scroll-back in the tab, and every connected host keeps its own state warm so switching back is instant.

The chrome bar shows a live memory figure for each process (server · client · kaval), so you can watch which one is climbing. Debug → Diagnostic info in the palette has the per-terminal detail, and its padi section splits padi’s memory into its JavaScript heap and what lies outside it. If the server or kaval figure keeps growing rather than the browser, a home-manager deployment can write heap snapshots and periodic process stats: see Deployment → Capture memory diagnostics.

Still stuck?