Landmarks

NamespaceRole
clai.coreCLI: nrepl, shell, web.
clai.replThe in-process REPL client: new!, prompt!, resume!, session namespaces.
clai.agent.coreThe agent: configuration, sessions, the chat loop, everything the daemon calls.
clai.agent.providers / .protocolProvider resolution and the provider interface.
clai.agent.tools.*Tool schemas, immutable registries, invocation, and the built-ins.
clai.events.schemaThe event vocabulary shared by the loop, the log, the REPL and the UI.
clai.events.compactionCompaction summaries and how a client replays them.
clai.daemon.postgres.*Session, note, plugin, config, git and stats storage.
clai.daemon.http / .nreplThe web daemon, the JSON API and the nREPL bridge.
clai.home.coreThe namespace eval_clojure runs in — the agent’s REPL.
clai.shell.*REPL-friendly git, docker, task, browser and process helpers.
clai.pluginsJar plugin loading and the middleware hooks.
clai.instrumentMalli collection and runtime instrumentation.
clai.configConfig discovery, resolution, and provider/storage client construction.
clai.lspclojure-lsp process management behind the LSP tools.

Four files carry most of the design: src/clai/repl.clj (driving a session), src/clai/agent/core.clj (the loop), src/clai/agent/tools/registry.clj (tools as values), and src/clai/agent/providers/protocol.clj (the provider seam).

clai.repl

Var / functionPurpose
current-sessionThe session selected in the calling namespace.
current-agentThe agent the REPL is connected to.
current-session-idThe id of the selected session, or nil.
connected?Whether an agent connection exists.
connect! / disconnect!Open or close the in-process connection.
new!Start a session and move the REPL into sessions.<id>.
resume!Resume a session by id (or the current/most recent one) and replay it.
history!Reprint a session’s history.
prompt!Send a prompt and stream the reply, tools, title, and compaction output.
session-nsThe namespace symbol for a session id.
namespace-builderCreate a session namespace through the plugin hooks.
$Run a shell command through sh -c.

clai.home.core

This is the agent’s REPL. It is an ordinary namespace, preloaded with:

FunctionReply
helpA cheat sheet of what the namespace offers.
toolsEvery tool the calling agent can use, sorted by id.
toolOne tool’s full JSON schema, or nil.
contextThe live eval_clojure context (cwd, session id, provider, model).
sessionThe stored session without its conversation.
historyThe stored conversation, oldest first.
active-pluginsThe plugins loaded in this process.
varsA namespace’s public Vars.
var-detailOne Var’s metadata, schema, source, and value.

Also referred: doc, source, apropos, dir, find-doc, and pprint. Aliases cover eval, registry, sessions, clj, plugins, json, shell, io, and str.

clai.shell.*

NamespaceExamples
clai.shell.gitstatus, diff, log, commit, checkout, branches, blame
clai.shell.dockerps, containers, inspect, logs, exec, compose-up, compose-down
clai.shell.tasklist, tasks, run, status, dry-run
clai.shell.clirun, run!, check!, pwd, cd, out, echo-result!
clai.shell.browserbrowse, browse!, command
clai.shell.helphelp, help!, help-text

Each returns a result map ({:command :exit :out :err :success? ...}) rather than throwing; the ! variants throw.

Providers

NamespaceRole
clai.agent.providersModel name → provider client; config → clients.
clai.agent.providers.protocolThe Provider protocol and the neutral pipeline.
clai.agent.providers.ollamaOllama client (local and ollama.com cloud).
clai.agent.providers.openrouterOpenRouter client.
clai.agent.providers.messagesNormalized assistant messages and tool calls.
clai.agent.providers.httpclj-http/JSON plumbing and NDJSON streaming.

protocol/respond returns {:message :usage :response}; protocol/complete returns just the assistant message. Both are what the agent loop, titles, and compaction use.

Storage

NamespaceTables / role
clai.daemon.postgresConnection handling and ensure-schema!.
clai.daemon.postgres.sessionsagent_session, agent_session_event.
clai.daemon.postgres.configsagent_config.
clai.daemon.postgres.pluginsplugin.
clai.daemon.postgres.gitgit_repo, git_worktree.
clai.daemon.postgres.notesnote, links, and search.
clai.daemon.postgres.statsUsage aggregates over the event log.
clai.daemon.postgres.usersapp_user, auth_token.

schema/schema.sql is the canonical DDL. ensure-schema! creates what is missing and never touches what exists.

Reading order

If you are skimming rather than reading:

  1. src/clai/repl.clj — how a session is driven.
  2. src/clai/agent/core.clj — the loop and its boundaries.
  3. src/clai/agent/tools/registry.clj — why tools are just maps.
  4. src/clai/agent/providers/protocol.clj — the provider seam.
  5. doc/plugins.md and web/README.md — the plugin contract and the full web protocol.