A plugin jar contains one entry namespace with a plugin Var. The Var is either a descriptor map or a function of the plugin’s JSON configuration that returns one.

(ns example.plugin)

(def plugin
  {:description "Adds a house style to every system prompt"
   :version "1.0.0"
   :hooks
   {:system-prompt
    (fn [ctx next]
      (str (next ctx) "\n\nAlways write tests before implementation."))}})
(ns example.plugin)

(defn plugin [{:keys [suffix]}]
  {:hooks
   {:system-prompt
    (fn [ctx next]
      (str (next ctx) "\n\n" suffix))}})

Ordering

Hooks run in this order:

  1. Lower :priority values first (a plugin row’s priority).
  2. Then by plugin name.
  3. Then in the order they appear in the plugin’s :hooks map.

Every hook receives a :plugin key containing {:name ... :config ...}.

Hook contracts

HookContextReturn
:namespace-builder{:opts ... :plugin ...} plus nextA namespace. Call (next ctx) for the default builder.
:system-prompt{:sys-prompt ... :cwd ... :agents-md ... :plugin ...} plus nextThe final system-prompt string. Call (next ctx) for the default prompt.
:user-prompt-pre{:session ... :messages [...] :plugin ...}Replacement message(s), or nil to keep the original.
:user-prompt-post{:session ... :messages [...] :plugin ...}Message(s) to append, or nil.
:agent-message-pre{:session ... :message ... :plugin ...}A replacement message map, or nil.
:agent-message-post{:session ... :message ... :update ... :plugin ...}A replacement update map, or nil.

A message hook may return a single message map or a sequence of message maps. A :user-prompt-* hook may also return a map with a :messages key. Hook exceptions are logged and ignored, so a broken plugin does not take down a session.

Adding Vars to session namespaces

:namespace-builder is middleware around clai.repl/namespace-builder. Call next to get the default namespace, then intern into it:

(defn plugin [_config]
  {:hooks
   {:namespace-builder
    (fn [ctx next]
      (let [ns (next ctx)]
        (intern ns 'deploy! (fn [] (println "deploying")))
        ns))}}})

Replacing the builder outright is allowed: return a different namespace without calling next.

System prompts

:system-prompt wraps the assembled prompt. The context carries the file’s :sys-prompt, the session :cwd, and the contents of an AGENTS.md in that directory as :agents-md. Call (next ctx) to get the default result, then return the string you want the model to see.

Selecting plugins

The plugin table stores each plugin’s name, jar path, entry namespace, JSON configuration, priority, and enabled flag. Which plugins run for a session is decided by:

  1. The session’s stored agent configuration plugins column.
  2. The config file’s :plugins key.
  3. Every enabled plugin.

NULL/omitted means every registered plugin, [] means none, and a vector of names or database ids means exactly those. Only hooks from active plugins are called.

Loading

clai.plugins/load-configured! loads the enabled rows at startup and on reload. The loader caches one URLClassLoader per jar path and rebinds Clojure’s compiler loader while requiring the entry namespace, so the plugin can require its own namespaces from the jar as well as clai namespaces from the parent class path.

Configuration changes apply on reload. Replacing code inside a jar requires restarting the JVM, because Clojure namespaces are not unloaded.

For manual experimentation:

(plugins/register! {:name "manual" :priority 50 :config {}}
                   {:hooks {:system-prompt (fn [_ctx next] (next {}))}})

The guide with worked examples is Writing plugins.