Plugin Hooks
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:
- Lower
:priorityvalues first (a plugin row’spriority). - Then by plugin name.
- Then in the order they appear in the plugin’s
:hooksmap.
Every hook receives a :plugin key containing {:name ... :config ...}.
Hook contracts
| Hook | Context | Return |
|---|---|---|
:namespace-builder | {:opts ... :plugin ...} plus next | A namespace. Call (next ctx) for the default builder. |
:system-prompt | {:sys-prompt ... :cwd ... :agents-md ... :plugin ...} plus next | The 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:
- The session’s stored agent configuration
pluginscolumn. - The config file’s
:pluginskey. - 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.