The Live Image

You can add a tool, change a command, swap a model provider, or remove a piece of behavior without restarting kli. The running session keeps going: your context, your session log, and the model connection all survive the change. That follows from how kli is built, which is what this page explains.

A small kernel, everything else an extension

kli is one running program. At its center is a small kernel: a registry of live objects and a single protocol that knows three operations — install a protocol, switch to it, and roll back to the previous one. That is nearly all the kernel does. It holds no model provider, no tool, no command, no rendering code.

Everything you interact with is an extension installed on top of the kernel. The model providers (anthropic, openai, openai-codex, and compatible), the tools that read and edit your files, the session log, the slash commands, and the terminal interface are all extensions. They were installed at startup the same way you would install one yourself, and they can be removed the same way.

An extension is a value before it is an effect. It declares what it requires and what it provides, and installing it runs through one step that records every piece it added to the protocol. Each kind of contribution has a matching retractor: a tool, a capability provider, a generic-function method, and a raw effect each install and drain through their own paired operations. Because installing was recorded, removing is possible, and removing an extension drains exactly the pieces it installed and nothing else. A slash command is one such extension: it registers through a capability provider and retracts with it.

What "while it runs" means

kli runs inside a live image. The image is a running Lisp process that holds the program and its state in memory at once, and that program can be redefined while it is running. This is the mechanism. It is why the kernel can install, retract, and replace extensions in a live session instead of regenerating a binary and starting over.

Replacing an extension is its own operation. The kernel deactivates the old version, draining its contributions, then activates the new source. If the new version fails to come up, the kernel reactivates the old one and reports the error, so a botched change leaves you where you started rather than in a broken state. The same holds for switching the whole protocol: a switch validates and smoke-tests the candidate first, and any failure rolls back to what was active before.

What this lets you do

The arrangement turns "change kli" from a build-and-restart cycle into an in-session action.

• Add behavior. A new tool or command is an extension; installing it makes it available in the current session.
• Change behavior. Redefining an extension's source replaces the running version, with automatic fallback to the previous version if the new one fails.
• Remove behavior. Deactivating an extension retracts its tools, commands, providers, and methods together, leaving the rest of the session untouched.
• Recover. Because every change is a recorded transaction, a failed switch or a failed recode returns the session to its prior working state instead of killing it.

You can also pull an extension from outside your machine. The in-session /install <url> <git-tree-sha1> command fetches a remote extension, shows a trust card describing what it is, verifies it against the git tree sha1 you pinned, and installs it only after you confirm. That consent step is separate from installing the kli application itself, which is the one-time curl -fsSL https://kli.kleisli.io | sh.

Why it is built this way

Making the kernel small and everything else a retractable extension lets you bend kli to a project — a tool that knows your build, a provider pointed at an endpoint you run — in the session that needed it, with no source edit or rebuild.

The kernel stays small on purpose. The fewer things it does, the fewer things can break when an extension is added or removed, and the more of kli can be treated as replaceable parts rather than fixed structure. The model providers themselves follow this rule — each one is an extension that installs a provider and retracts it cleanly, interchangeable parts rather than one wired-in default.

Related

• Profiles — how groups of extensions are bundled and selected.
• Permissions and capabilities — the capability set that gates installing, retracting, and recoding behavior.
• Connect a provider — installing and configuring a model provider extension.
• Installation — installing the kli application.