The built-in tools are grouped by concern, and each group is a namespace under clai.agent.tools.builtin. An agent configuration can enable a subset of them; clai.edn can too.

ToolWhat it does
read_file, write_file, list_directoryRead and write files, resolved against the session’s cwd. read_file takes an optional line range so a long file can be read in slices instead of flooding the history.
run_commandRun a shell command in the session’s cwd, with output capped.
eval_clojureEvaluate Clojure in the harness’s own JVM, in clai.home.core. Results persist between calls; the agent is encouraged to def values worth keeping so they are visible in your REPL too.
spawn_agentRun an isolated sub-agent with its own system prompt, model, tool subset, and working directory. Only its final reply comes back, so the parent’s context stays small. Nesting is capped.
lsp_definition, lsp_references, lsp_hover, lsp_symbols, lsp_outline, lsp_diagnosticsNavigation over clojure-lsp, kept warm per project. Beats grepping for defn when the agent needs to know which error-message on which line is meant.
notes_list, notes_search, notes_read, notes_update, notes_deleteTitled Markdown notes in PostgreSQL, BM25-ranked.
openproject_*List projects and work packages, create and update tasks, and read, add and edit task comments — when :openproject is configured.

The OpenProject tools are openproject_list_projects, openproject_list_work_packages, openproject_create_work_package, openproject_update_work_package, openproject_list_comments, openproject_add_comment, and openproject_update_comment, so an agent can work a task the way you would.

Tools are values

A tool is a map of {:id :handler :spec}: an LLM-facing JSON schema plus a plain function (fn [args ctx] ...). There is no global tool registry.

(require '[clai.agent.tools.registry :as registry]
         '[clai.agent.tools.builtin :as builtin])

(def tools (builtin/built-in-registry))   ; an immutable map, owned by you
(def narrowed (registry/select-tools tools ["read_file" "eval_clojure"]))

Registries are immutable maps owned per agent, so two agents in one process can offer different tool sets. Adding a tool is assoc.

eval_clojure can inspect the calling agent’s live registry:

(tools)          ; every tool this agent can use, sorted by id
(tool "read_file") ; the full JSON schema of one tool

Sub-agents

spawn_agent starts a child agent with its own system prompt, model, tool subset, tool-round cap, and working directory. It defaults to a focused sub-agent prompt and to every tool except spawn_agent itself.

{:prompt "Find every place the WebSocket protocol is documented."
 :system_prompt "You are a precise codebase researcher."
 :tools ["read_file" "list_directory" "lsp_references"]
 :model "openrouter:anthropic/claude-sonnet-4"
 :cwd "/home/me/code/clai"}

Only the child’s final reply returns to the parent, so the parent’s context stays small. Nesting is capped.

Behaviour around the tools

  • Compaction. When a session’s history outgrows its token budget, the agent summarizes it in one request and appends a compaction event. Reading the history skips the events the summary covers and keeps the system prompt, the summary, the newest messages, and the turn in progress.
  • Automatic titles. A new session is named from its first prompt by one extra model call, so the sidebar is readable without typing titles.
  • Output caps. Every tool result is capped (64 KiB by default) so a single runaway command cannot eat the context window.
  • Per-agent registries. Tools are not global. Each agent owns a registry map, which is what makes a narrowly-tooled sub-agent, or two agents with different capabilities, possible in one process.

The tool reference lists every tool id with its arguments.