agent-distro
Type `claude`.
It's already there.
kolu can bring the AI coding agents along: Claude Code, Codex, OpenCode, Pi
and Oh My Pi, kept up to date, with nothing to install. Switch them on, open a
new terminal and type claude. Each agent starts with kolu’s plugin loaded, so
it can drive your other kolu terminals.
The agents are a switch: on, every new terminal gets them, as
agent-distro ships them. Profiles
are an ordered list on top of them, each a git repository of skills, MCP
servers and settings, such as Juspay’s (github:juspay/skills).
First run
kolu adds no agents until you switch them on. It asks in the welcome card whenever no terminals are open, in the palette’s Tutorial, and in Settings → Agents.
- Add a profile, if you want one: one click adds + Juspay — Juspay skills + Kolu, via Juspay’s LiteLLM gateway. The list is otherwise empty.
- Click Turn on ⏎. It has the keyboard already, so Enter does the same, and nothing is written until you do.
- Or click Not now — plain terminals, ask again later. The question comes back the next time the welcome card appears.
Terminals your session brings back after an upgrade get no welcome card, and no agents until you switch them on.
Settings → Agents
Open Settings (the gear in the top bar). The Agents row holds the switch and the profile list, for all of kolu: not per host, not per terminal. kolu tells you what changed for new terminals.
Chips under the switch name the agents and this machine’s versions. A fleet line under them covers every machine at once, and each machine’s name opens its host details (On other machines).
Profiles
A profile is an Agent Plugin in any git
repository: a plugin.json at its root carrying its skills and MCP servers,
the commands those servers need, and the env and settings it gives every agent.
Each row of the profile list says whether its profile builds, and the revision it was fetched at. If it does not, Nix’s or agent-distro’s own words say why, in red. ✕ removes a row; with two or more, each can also move up or down.
Add one with the field under the list: click it for suggestions, or type a
flake reference (github:you/your-profile) or a path (~/src/my-profile, or
an absolute one) and press Enter.
While a profile in the list does not build, new terminals get no coding agents at all. Fix it and kolu tries again at the next check and when you edit the list, or remove the row.
How profiles stack
Profiles apply in list order, each over the one above it: where two set the
same thing, the lower one wins. A repository’s own plugin.json comes last of
all, so opening an agent there composes that profile over your whole list. The
list ends with a row saying so, which you cannot edit or remove.
A repository’s profile brings its own plugins and MCP servers, so open
terminals only in repositories you trust, as with a .envrc.
Built once, by kolu
The machine running kolu builds each profile: it fetches it, notes the revision it found, and builds it with agent-distro’s own builder, which fetches any plugin the profile names by a flake reference. The result goes to every machine beside the agents (On other machines).
A terminal gets the built profiles as its AI_PROFILE, so starting an agent
compiles nothing and works offline. A path is read on the machine running kolu,
so a profile in ~/src/my-profile there reaches every host. Every look for
newer agents builds each profile again (Kept up to date).
What a profile holds is agent-distro’s own format
(Profiles, and
From APM for a repository with an
apm.yml).
Which agents a terminal has
A change applies to the next new terminal. One already open keeps exactly the
agents it started with, since kolu puts that exact build on its PATH. A pill in
its title bar names the profiles in effect, as agent-distro names a stack
(juspay + my-repo), and a short hash of the agents’ build. No pill means
agents were off when that terminal started.
Restarting a terminal onto the current agents
When a terminal’s agents are no longer what a new terminal there would get, its pill dims and becomes a Restart button. While kolu is still delivering a set to that machine, or the delivery failed, it offers no Restart: restarting then would leave the terminal with no agents at all.
Restart gives the terminal a fresh shell in place, with the current agents, in the same tile, folder and theme, and its splits restart with it. The agent’s conversation resumes on the new agents, any other program in the terminal ends, and with agents off it comes back as a plain shell.
If an agent is working or waiting for you, the first click only asks; a second
click within a few seconds confirms. The old shell is killed outright, so it
writes no history file, and nohup jobs keep running.
The same restart is the tile’s ↻ button and Restart terminal in the command palette (Inside a Tile).
Where they sit on the PATH
With agents on, a new terminal’s PATH reads, from the front:
- kolu’s own tools (
kolu,kaval-tui,padi-tui), - the agents,
- your own PATH, including anything your shell’s dotfiles add.
So the bundled claude wins over one you installed yourself, which stays as
the fallback. kolu re-applies this order after your .bashrc or .zshrc runs,
so a dotfile that puts its own directory first
(export PATH=$HOME/.local/bin:$PATH) does not undo it. Other shells get the
order at spawn only (Shell integration). To run your own
claude, turn agents off or call it by its full path.
The agents also bring the agent-distro command: it lists the profiles in
effect here, the agents, their versions and who is signed in, and launches one.
On other machines
Agents work the same on every host you add. The machine running kolu delivers them.
- kolu looks up which build of the agents the host needs, in agent-distro’s published index.
- Over the ssh login kolu already uses, the host downloads that build from agent-distro’s binary cache and pins it against Nix’s garbage collection. That cache holds everything the build needs, and the host reads no other.
- Your profiles go the same way, built here for the host’s kind of machine and copied into its store over the same login.
A host needs only the ssh login, nix on the PATH of that login, and outbound
HTTPS to the cache: no flakes, no GitHub access, nothing compiled on either
side. A Mac must also trust the login or the cache’s key
(When a delivery fails).
Each host tab carries agent-distro’s mark after the host name:
| The mark | What it means |
|---|---|
| plain, in the tab’s text colour | Ready for new terminals. |
| a turning arc around it | Delivering the agents to it. |
| plain, with a turning arc around it | Ready; a newer set is on its way. |
| plain, with a small warning dot | Ready and working, but its last update failed. |
| warning colour with a small dot | The delivery failed. |
| no mark at all | Agents are off, or this host has none. |
Click the mark for that machine’s host details: the profile and build new terminals there get, and check for newer agents ↻.
The machine running kolu needs no delivery: the agents ship inside kolu. Its
own cache carries them for x86_64 Linux and Apple Silicon; on aarch64 Linux the
first nix run compiles them instead
(the binary cache).
Kept up to date
agent-distro publishes a newer tested set of agents up to four times a day, at 02:00, 08:00, 14:00 and 20:00 UTC. At those times kolu looks for a newer build of the agents and a newer revision of each profile, and delivers what is missing to every connected machine.
Changing the profile list delivers it at once, and a machine also gets a delivery whenever it connects, so one that was away catches up. A failed run is tried again up to twice, five minutes after it ended.
While a newer set is on its way, the one you have keeps serving new terminals. When it lands, a toast says what changed and on which machine, and an open terminal keeps its own set and offers Restart (above). Only the serving set is protected from Nix’s garbage collection.
A check that finds nothing newer says nothing, and a failed update pops no toast, since your agents keep working. Both show in that machine’s host details, with its last five update events in agent-distro’s own words.
To look now, use the palette’s Check for newer coding agents for every connected machine, or check for newer agents ↻ for one, greyed out while that machine is away or a delivery to it is running.
When a delivery fails
A delivery that fails leaves the host with no agents, and its tab mark turns the warning colour. kolu tries again on the schedule above, or now, from that machine’s host details, which carry the cause in full.
| Cause | What to do |
|---|---|
| agent-distro has not published the agents for that kind of machine yet | Nothing; kolu tries again on its schedule. |
| a profile would not build | Fix it or remove it. The cause is under its row in Settings (Profiles). |
| a profile lists commands for the host’s kind of machine | The machine running kolu cannot build those; the failure names it and both kinds of machine. |
| the host could not reach the cache, or the download broke off | Nothing; kolu tries again. |
| the host’s Nix does not trust what it was sent | Add the login kolu connects as to its nix.settings.trusted-users, or agent-distro’s cache key to nix.settings.trusted-public-keys. |
A Linux host on Nix 2.17 through 2.34 has to trust nothing: the agents reach it content-addressed, each store path named by the hash of what it holds. A Mac, and a Linux host on Nix 2.35 or later, gets the signed agents instead, and takes them only if its Nix trusts the login or the cache’s key.
A profile is built here and signed by no one. It goes content-addressed only when this machine’s Nix and the host’s sit on the same side of Nix 2.35, and as built otherwise, which a host takes only if its Nix trusts the login. A refusal names the versions that disagreed and the one-line fix.
Turning it off
Settings → Agents, switch it off. From the next new terminal on, on every host, kolu adds no agents and no plugin variable. Terminals already open keep what they have until you close them, or restart them, which brings them back as a plain shell. Your profile list stays for when you switch them back on.
Agent detectionkolu watches the agent running in a terminal, whichever claude it is. Add another machineThe hosts kolu delivers the agents and your profiles to.