Tools
A tool is a map of {:id :handler :spec}. The :spec is the JSON schema the
model sees; the :handler is (fn [args ctx] ...). Registries are immutable
maps owned per agent, so enabling a subset for one agent does not affect
another.
Files
| Tool | Arguments | Notes |
|---|---|---|
read_file | path, start_line?, end_line? | Paths resolve against the session’s cwd. Line ranges are 1-based and inclusive. |
write_file | path, content | Writes the full text of the file. |
list_directory | path? | Defaults to the session’s cwd. |
Shell
| Tool | Arguments | Notes |
|---|---|---|
run_command | command | Runs via the shell in the session’s cwd; output is capped. |
Clojure
| Tool | Arguments | Notes |
|---|---|---|
eval_clojure | code, namespace? | Evaluates one form in the harness’s JVM. Defaults to clai.home.core; a namespace that is not loaded is required from the classpath. |
eval_clojure code runs in the same process as the REPL and the web daemon.
Values defined with def persist between calls. The default namespace
provides help, tools, tool, context, session, history, vars,
var-detail, and active-plugins, plus aliases for the namespaces an agent
most often wants.
Sub-agents
| Tool | Arguments | Notes |
|---|---|---|
spawn_agent | prompt, system_prompt?, tools?, model?, max_rounds?, cwd? | Runs a child agent and returns only its final reply. Nested sub-agents are allowed up to a small depth limit. |
The child defaults to every parent tool except spawn_agent, the parent’s
model and working directory, and a focused sub-agent system prompt. Pass
tools: [] for no tools. max_rounds is clamped to 32.
clojure-lsp
All six tools use clojure-lsp, kept warm per project. Position-taking tools
accept symbol, or file plus a 1-based line and optional column.
| Tool | Arguments | Notes |
|---|---|---|
lsp_definition | symbol?, file?, line?, column? | Where a var or namespace is defined. |
lsp_references | symbol?, file?, line?, column? | Every place a var or namespace is used. |
lsp_hover | symbol?, file?, line?, column? | Signature, docstring, and source location. |
lsp_symbols | query, limit? | Search vars and namespaces by name substring. |
lsp_outline | file | The namespaces and vars one file defines. |
lsp_diagnostics | file? | Lint problems for one file, or the whole project when omitted. |
Only the project’s sources are indexed. For clojure.core or library vars,
eval_clojure with (doc ...) or (source ...) is the fallback.
Notes
Notes are titled Markdown documents in PostgreSQL. Links are written as
[[Note title]] and read out of the content rather than stored separately.
| Tool | Arguments | Notes |
|---|---|---|
notes_list | none | Most recently updated first, with id, title, time, and a preview. |
notes_search | query, limit? | BM25-ranked when pg_textsearch is available, substring otherwise. |
notes_read | id | Content, links, backlinks; long content is truncated. |
notes_update | id, title?, content? | Partial update; omitted fields keep their stored value. |
notes_delete | id | Permanent. |
OpenProject
These tools are available only when :openproject is configured.
| Tool | Arguments |
|---|---|
openproject_list_projects | query?, page_size?, offset? |
openproject_list_work_packages | project?, status?, type?, assignee?, priority?, subject?, filters?, sort_by?, page_size?, offset? |
openproject_create_work_package | subject, project?, plus description, status, type, priority, assignee, parent, start_date, due_date, estimated_time |
openproject_update_work_package | id, plus any writable field, project?, lock_version? |
openproject_list_comments | id, limit?, include_changes? |
openproject_add_comment | id, comment |
openproject_update_comment | id (comment/activity id), comment |
openproject_list_work_packages applies OpenProject’s default open-work-package
filter when no filters are given; pass filters: "[]" to include closed work
packages too. Updates fetch the current lock version automatically when it is
not supplied.
Limits
- Every tool result is capped (64 KiB by default) so a runaway command cannot consume the context window.
:max-tool-roundscaps consecutive tool-call rounds per prompt.- A session’s history is compacted when it exceeds
:compact-after-tokens.