What is clai?

clai is an AI agent harness written in Clojure, built so that the agent and the developer work in the same live JVM. It is a personal tool rather than a product: opinionated, changing most days, and with no compatibility promise.

The defining idea is that the agent’s most powerful tool, eval_clojure, evaluates code in the harness’s own running Clojure process — the same process that serves the web UI, streams events, and holds your REPL. The agent can read its source, redefine a function, and reload a namespace. So can you, at the same time. Clojure is the shared language between the human and the agent, not just the implementation language.

How it fits together

clai (one JVM)
├── clai.daemon.http ── the React UI (/ws, /api) and the JSON API
│   └── nREPL bridge ── the REPL panel and `clai shell` evaluate through it
├── clai.agent.core ── the chat loop, sessions, tool calls
│   ├── providers ── Ollama, OpenRouter
│   ├── tools/builtin ── files, shell, notes, lsp, sub-agents
│   │   └── eval_clojure ── evaluates in this same JVM
│   └── postgres ── sessions, event log, notes, plugins, stats
└── clai.repl ── new!, prompt!, resume!: the agent driven from a REPL

A prompt enters through the REPL, clai.repl, or the WebSocket. The agent loop sends the session history to the provider that serves the selected model, runs any tool calls the model asks for, appends the results, and repeats until the model replies in text or the tool-round cap is reached. Every step is streamed as an event and appended to the session log in PostgreSQL.

Sessions can be driven from two places without changing their storage:

  • The REPL — lein repl starts in user, with the clai.repl helpers referred. new!, prompt!, and resume! talk to the agent directly.
  • The web UI — clai web (or lein run web) serves a React app, a JSON API, and a WebSocket on port 8080.

Safety first

clai is not sandboxed. The agent can run arbitrary shell commands, write any file the JVM can write, and evaluate any Clojure form in the harness’s own process. That is the feature, and it is also the risk.

  • Run it in a container or a VM you do not mind losing.
  • The nREPL server binds to 127.0.0.1. An nREPL client can execute arbitrary code in that JVM, so do not expose the port.
  • The web daemon is authenticated, but binds to 0.0.0.0 by default. Set :host to 127.0.0.1 on clai.daemon.http/start-server! if you want it local-only.
  • Change the seeded admin / admin account before the daemon is reachable by anything but you.
  • A PostgreSQL dump is sensitive: it holds everything you and the model said to each other.

Prerequisites

  • A recent JDK (21 or newer; the project is developed on 25).
  • Leiningen.
  • Docker, for the development PostgreSQL.
  • Node.js and Task if you want the web UI.
  • An Ollama server (local or hosted) and/or an OpenRouter API key.

Quick start

# 1. Local PostgreSQL for sessions (localhost:5432/clai, user clai, secret)
docker compose up -d

# 2. Optional: point clai at a model
cp config.example.edn ./clai.edn     # then edit :model, :provider, keys

# 3a. Web UI + API + nREPL on :8080
task web

# 3b. …or the REPL, which drives the same agent in-process
lein repl

The Docker Compose database already matches the built-in connection defaults, so a fresh checkout needs no configuration to reach it. config.example.edn is commented key by key; configuration is resolved from the first file that exists of $CLAI_CONFIG, ./clai.edn, and ~/.config/clai/config.edn.

The web UI opens on a sign-in form. A fresh database is seeded with admin / admin; change it before exposing the daemon. See Configuring models and providers for the full configuration story.

Your first session

From the REPL:

(new!)                                   ; new session, REPL moves into sessions.<id>
;; => {:sessionId "12" :cwd "/Users/me/code/clai" ...}

(prompt! "How does compaction decide what to keep?")
;; clai> Compaction keeps the system prompt, the summary, the newest
;;       messages and the turn in progress...
;;   [tool] 418 completed
;;      ...
;;   [title] Compaction rules

(history!)                               ; reprint the conversation so far
(resume! "9")                            ; jump back into an old session

From the browser:

http://127.0.0.1:8080

Sign in, start a session, choose a working directory, and type a prompt. The REPL panel in the same window evaluates Clojure in the daemon’s JVM, and the Namespaces explorer shows the live runtime the agent is editing.

Next steps