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:
- Secure context. Notifications ride a service worker, which needs HTTPS
or
localhost. From another device gives kolu a private HTTPS URL. - Browser permission. Re-enable notifications from the address-bar lock icon if you dismissed the browser prompt.
- 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:
- 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/projbecomes-home-me-proj), holding a<timestamp>_<uuid>.jsonltranscript. No file, no badge. - 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.
- kolu only scans
~/.xyne. Point Xyne’s home elsewhere through a wrapper and detection cannot follow it. Tests and development overrides useKOLU_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.
| Button | What it does |
|---|---|
| Restore the newest backup that reads | Walks 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 works | Starts 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.
| Part | What it shows | What a bad number means |
|---|---|---|
| Child processes | Each 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. |
| Stalls | How 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 watchers | One 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. |
| Watches | The 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. |
| Memory | padi’s resident memory, its JavaScript heap, and what lies outside the heap. | Growth outside the heap is native memory, such as file watches. |
| Calls | Each 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
| Asker | Who it is |
|---|---|
terminal <id> | That terminal, following the git repository it sits in. |
stream subscribeRepoChange | A 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 detection | kolu 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-change | Nobody, 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:
| Cause | What asked |
|---|---|
context | A terminal or a work moved to a new repository, branch or remote. |
poll | The 30-second recheck of a pull request kolu already follows. |
refresh | The 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:
- 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.
- 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.
- 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.