kmet - Coding Agent Written in Clojure

My previous post about rab ended with a promise: "maybe next time I'll start from scratch with all the lessons learned."

kmet is that next time. It breaks exactly one rule from that post: the language.

rab rejected Clojure on four grounds, in a paragraph I still stand behind as reasoning:

TUI libraries in Clojure are virtually non-existent. JVM startup times kill the instant-feedback loop a TUI tool needs. Memory footprint is an order of magnitude higher. And most critically: even the best LLMs generate poor Clojure code.

kmet is a terminal-first coding agent written entirely in Clojure. Those four claims were accurate when I wrote them. Two of them were about the runtime rather than the language, and one of them stopped being true. Getting from that paragraph to a working daily driver is most of this post.

The other reason is unchanged from rab: I wanted to understand coding agents from the inside out, and building one is the only way I know to do that.

A coding agent in the spirit of pi: a terminal interface, my own tool loop, my own provider layer, no IDE dependency and no browser. Streaming conversations, a multi-line editor, a set of primitive tools, sessions on disk, extensions loaded at runtime.

The addition since rab is architectural. rab's problem was never the agent loop, it was that every feature touched three subsystems. kmet is organised around the opposite premise: everything is a plugin. The loop, the tools, sessions, model access and the run modes are rows in a composition, not code in an entry point. An extension mounts beside the core instead of patching it. That is not my idea, and it is credited below.

kmet runs from one source tree on three hosts: Babashka as the primary runtime, native Jolt for self-contained binaries, and the JVM. Same namespaces, same behaviour, different startup cost.

kmet (Cyrillic кмет) is an old Slavic word with two opposite senses, and Serbian keeps both. A kmet is the village elder, the first man of a community and its judge. A kmet is also the bondsman bound to the land he works. Other languages keep one half: Bulgarian кмет is mayor, Slovene kmet is farmer.

Both senses fit a coding agent. It decides what to do next and it does the work it is told to do, in a codebase that belongs to someone else.

The kernel is called srce (срце), Serbian for heart. Cordis is the Latin word for the same thing, which is where the name comes from. srce lives in its own module and carries its own documentation.

Three projects deserve naming.

pi is the functionality. kmet is a close port of pi's stable interactive core: the component model, the TUI, the agent loop, the tool set, the provider and auth subsystem, sessions, compaction, skills, prompt templates, themes, and the extension API. I use pi daily and treat its behaviour as the specification. Where kmet differs, the difference is deliberate and tracked in a gap document.

DeepSeek Harness (dsh) is the architecture. One context tree, services found by key, dependencies declared, effects that unwind, extensions mounting beside the core. Five of its decisions are folded in directly: an agent handle kept separate from the append-only session log, an agent loop that provides a service so the run modes wait for it instead of starting it, a --dump-config that composes the row tree with the same patch algorithm boot uses, a per-agent scoped setup composed before the agent is published, and the profile/bundle/patch composition model. I declined three: web-first, npm as the plugin boundary, and live recomposition of a running composition.

Cordis is the kernel. It is a plugin meta-framework in TypeScript, and dsh is built on it. Its five ideas are: a plugin is a service with optional injection and an apply function; a context is a repository of services found by key; dependencies are declared, so load order stops mattering; events are typed and dispatched; registrations are reversible effects. kmet's kernel reduces those five to four Clojure namespaces and about nine hundred lines, with nothing vendored. A plugin is a map with :inject and :apply rather than a Service subclass, there are six synchronous event modes rather than awaiting ones, and there is no logger subsystem, interception chain or drain thread.

Everything in kmet is either ported from those three projects or is a consequence of porting them to Clojure.

The kernel. srce is four namespaces, one public one (kmet.srce.core), no third-party dependencies, and no clock, queue or protocols. A plugin is a map. It declares what it needs, it becomes active when those services exist, and unmounting unwinds everything it registered in LIFO order. The consequence that matters daily: mounting an extension, a profile row and a run mode can happen in any order, because nothing asserts boot sequence, and /reload is one call rather than a convention every subsystem has to remember.

One namespace is the ABI. An extension is a namespace that requires kmet.extension and defines a plugin var. It gets a ctx, a map of capabilities, and its own SCI context with its own deps.edn, so an extension can depend on a library kmet does not have, and reloading it does not restart the app. Registration is a function call on the api map, not a mutation of anything global. There is no compatibility promise before 1.0 and the in-repo extensions move with the contract, which keeps the contract small enough to read in one sitting.

(ns my.hello-ext
  (:require [kmet.extension :as ext]
            [kmet.srce.core :as srce]))

(srce/defplugin plugin
  {:name  :ext/hello
   :apply (fn [_ctx api]
            (ext/register-command! api
              {:name        "hello"
               :description "Say hello"
               :handler     (fn [_ args] (str "Hello, " args "!"))})
            nil)})

That is the whole extension. The nil return matters: a body that starts background work answers nil, not the future it started, because every registration the body made is already an effect on its fiber and unmounting unwinds them in order.

run_code. The tool that does not exist in rab. It runs model-written Clojure in a per-call SCI sandbox with the agent's own tools bridged in as functions, so a script can call (read ...), shell out, or ask for a tool's schema, and then emit only a digest. When a task is "scan two hundred files and tell me which ones", the model writes fifteen lines of Clojure and prints three values instead of reading forty files into its own context. Facts are computed in the sandbox, and only the result crosses the wire.

;; count what the tree is made of, emit only the digest
(->> (fs/glob "." "**/*.clj")
     (map #(-> % fs/file-name str))
     frequencies
     (sort-by val >)
     (take 5)
     (emit))

Context economy as a design constraint. The mcp adapter and the lsp adapter are each one tool, a proxy of roughly two hundred tokens that discovers and describes what is behind it. Hundreds of tool definitions, which is what a naive MCP client ships, is a permanent tax on every request. One tool for a family of operations beats ten thin ones.

Babashka first, dialects after. kmet targets Babashka as its primary runtime, and every commit since the first one was written against it. Babashka's author built it as Clojure without the JVM: millisecond startup, a large part of the language and the ecosystem already there. A bb-first tree has therefore already answered the questions a port asks. Does this touch a class, does it need a build step, does anything assume the JVM. The discipline shows up as plumbing rather than architecture (babashka.fs instead of java.nio, babashka.process instead of ProcessBuilder), and it is the reason adding two more hosts was work rather than a redesign.

Jolt is a dialect, and the port went well. Jolt is not a faster way to run the same Clojure. It is a new Clojure dialect by Yogthos with its own native runtime, so porting to it is a conversation rather than a download. Yogthos is responsive, the issues I filed mostly came back fixed upstream, and the fixes were improvements to the dialect rather than one-off patches for me. A user who runs a young host hard and reports what breaks helps that host, and a host that answers quickly helps the user. Both projects moved forward.

Three hosts. Babashka for development and startup, Jolt for self-contained native binaries, the JVM where a real classpath is required: one source tree, three views of the same namespaces.

Dogfooding from the start. kmet has been my daily driver for most of its life. Find a missing feature, add it as an extension, reload, use it in the same session. That loop is as productive as it was in rab, and I debug kmet by running kmet on kmet.

kmet started as a port and is not one any more. The alignment document records the gaps against pi 1.3.0, but closing all of them is not the goal. A new pi feature now falls into one of three groups: port it, decline it, or leave it out because it does not fit what kmet is.

The frame path, and specifically the cost of the inline TUI.

I render into the terminal's native scrollback instead of owning an alt-screen viewport, because the transcript belongs there: the user browses history with the terminal's own keys while output keeps streaming below. That decision is correct and expensive. The terminal has no addressable scrollback, so any change that lands above the window cannot be repainted. kmet clamps such a diff to the window top, records that the scrollback is now stale, and rebuilds it with one clearing full redraw at a boundary where the user is not mid-stream. Getting that wrong means a viewport that jumps to the top in the middle of a response, which is what a naive full redraw does on some terminals.

The rest of the renderer exists to keep that rebuild rare. Records cache their lines per width, a tool block's body is constant for its whole life so a pending-to-success transition cannot touch history, and frames emit the minimal diff. It works, and it is more machinery than any other part of the UI, all of it in service of a property the user never sees. The hard part of this project is not the agent.

The other thing I did not enjoy is inherited from a young host. Jolt is fast-moving and incomplete in ways that are invisible until you hit them: a missing JDK member, a constructor arity, a class that the runtime models but does not fully supply. The library in jolt/ exists to declare those gaps. At the moment it is empty by design because the runtime caught up, but I have spent evenings on tickets that a mature host would never have raised. What made those evenings worthwhile is the other half of the trade: almost every ticket I filed came back fixed, #1031 excepted, and each fix improved the dialect for everyone rather than unblocking me alone. I still carry the scaffolding for the next gap.

rab's cracks were architectural: too many moving parts, and the fix was to stop owning the base layer and build on yoagent.

kmet's first version had the mirror-image problem: a process-global registry node, sixteen mutable process globals, and a per-extension capability map that had to be updated whenever a capability was added. It worked, in the way that a global works, until two mounting orders disagreed about who owned a name. Nothing about that is specific to Clojure. It is what you get when a plugin system grows a string of globals one special case at a time.

The fix was the kernel, and it was not a refactor. Services became keys on a context tree, dependencies became declarations, and every registration became an effect owned by the fiber that made it. A mechanism belongs in the kernel only if it passes all three tests: the application needs it as a service, it is what separates a kernel from a service locator, and it could not be added later without changing every caller. Everything else is deferred rather than dropped, with the seam that makes re-adding it additive recorded next to its Cordis ancestor. That record is why I could cut a full port of ten namespaces down to four without losing track of what I removed.

The change in one comparison:

;; before: sixteen process globals, one per capability
(defonce tools (atom {}))
(defonce events (atom []))
(defonce renderers (atom {}))

;; after: the ctx holds the name, the fiber owns the disposal
(srce/provide! ctx :tools table)

What is still cracked: the composition is edited by humans. There is a --dump-config that composes the row tree exactly as boot would, and a generated catalog that the build verifies, but a model-facing tool that edits composition and reports applied versus restart-required does not exist yet. Live recomposition of a running composition, which dsh has, is declined until it can be scoped to leaf rows whose disposal no dependent re-resolves. Until then, enabling an extension means editing a patch file and restarting.

The patch file is a composition, and it is three lines:

;; ~/.kmet/agent/patch.edn
{:rows [{:id :ext/clojure :plugin :ext/clojure}]}

The 90% problem did not go away. It moved.

The alignment document is a six-hundred-line list of what pi has and kmet does not, refreshed against pi 1.3.0 and kept current. Reading it is the fastest way to know what is missing. Most of it is small: a slash command, a setting, a rendering detail. Some of it is not.

Provider coverage is aligned on paper (forty-odd model catalogs, OAuth, custom models, the auth flows) and tested on the ones I use. Anthropic, Gemini, Bedrock, the local servers: I have not exercised them daily, so they are as good as my reading of their documentation. That is the same standard of quality rab had for its providers.

And there is still one user. kmet has releases, a test suite, a lint gate with zero tolerance for warnings and a formatter that runs on every change, so it is not a prototype. But a bug nobody has hit is a bug that is still there, and the edge cases (a terminal resize mid-stream on Windows, a SIGPIPE, an unusual TTY) are found by users, not by me.

Three tracks have a foundation and no finished product.

rab is the post where I went back to pi. kmet is the one where I do not.

I use kmet every day. That is a different ending for the same reason: the language stopped being the obstacle. When something is wrong, the fix is in Clojure, in a codebase I can read end to end, at whichever layer the bug actually lives (editor, renderer, tool, kernel, loader). With rab I was always choosing between three subsystems I did not fully own. With kmet the whole stack is one artefact I can hold in my head, and the extension boundary means a new behaviour is a twenty-line file rather than a patch in a privileged core.

The gaps are still there and still listed. But "restart-required" is a better place to stand than "no users, no motivation".

Adopt the reference architecture, not just the reference features. rab gave me the agent loop and nothing else, so every feature I added had to invent its own place. Starting from a plugin model instead (services by name, dependencies declared, effects that unwind) meant the second and third features were cheap, and /reload was possible without an architecture change.

A plugin system is small until you add a global. The kernel is nine hundred lines because it refuses to do five things. Every mechanism it declined has a recorded seam, so re-adding one is a lookup rather than a redesign. The temptation to add "just one" convenience is the erosion the deferred table exists to resist.

Start with the smallest host. A tree that runs on Babashka runs everywhere. The reverse is not true. Picking the leanest dialect first turns portability from a rewrite into a negotiation, and it makes the reader conditionals a fact about the code rather than a flag you add later. Two more hosts cost me plumbing (babashka.fs instead of java.nio, :bb and :jolt branches, generic helpers in a shared libs layer) and not a second architecture.

Give the model better tools before blaming the model. A form-aware editor, a format-on-changed-forms pass, and a sandboxed script runner did more for Clojure generation quality than any prompt I have written. Then the models got better anyway, and I had to admit the second half.

The renderer is the hard part. The scrollback machinery is the most complex code in the project and it adds no features. That is where the engineering is, and it is the part I would have got wrong if I had copied a framework instead of writing one I could debug.

kmet lives at https://github.com/kmetia/kmet-agent. It is under active development and it is ready to use: it runs on Linux, macOS, Windows, WSL and Termux, it has releases, and it is the tool I use for my own work every day.

If you write Clojure, use it on a real project. Bug reports, feedback and pull requests are welcome, and the issue tracker is the fastest way to get something looked at.