lein repl starts in the user namespace, which loads the harness, redirects its logs to a file so they do not interleave with the conversation, and refers the REPL helpers and the shell integration namespaces. The whole agent is then a handful of functions.

The core helpers

(new!)                    ; start a session; the REPL moves into sessions.<id>
(new! "/path/to/project") ; …with an explicit working directory

(prompt! "Why does this test fail?")
;; clai> Reading the failure and the implementation...
;;   [tool] read_file completed
;;   [tool] eval_clojure completed
;;   [title] Failing test investigation

(history!)                ; reprint the current conversation
(resume!)                 ; resume the current or most recent session
(resume! "9")             ; resume a specific session

new! and resume! both move the REPL into the session’s namespace. That namespace is sessions.<id>, seeded from user with the same helpers and aliases, plus its own current-session and *cwd* Vars. Creating or resuming a session therefore changes where subsequent evaluations run.

prompt! streams events as they arrive: model text, thoughts, tool calls and their output, generated session titles, and compaction summaries. The REPL reads like a conversation rather than a blocking call.

Session namespaces

Every session gets its own namespace for three reasons:

  • Two sessions do not fight over *cwd* or over a helper Var one of them redefined.
  • A session namespace survives for the life of the process, so returning to it restores its definitions along with its conversation.
  • The web REPL panel defaults to the same namespace, so the panel and clai.repl address the same session, working directory, and definitions.

Namespace creation goes through clai.repl/namespace-builder, which is a plugin hook. A plugin can seed session namespaces with extra Vars or replace the builder entirely.

(in-ns 'sessions.12)      ; or just stay where new!/resume! put you
current-session           ; the session map selected in this namespace
*cwd*                     ; the directory shell helpers resolve against

Shell helpers

The clai.shell.* namespaces are ordinary, composable Clojure functions for git, docker, task, and the browser. They are what the agent’s run_command and eval_clojure reach for, and they are what you type in the REPL.

(->> (git/status {:dir "/repo"}) :untracked (map :path))
(-> (docker/inspect "my-container") first :state)
(binding [*cwd* "/repo"] (git/status) (task/list)) ; in a session ns
($ "lein test")           ; anything, via sh -c
(help! git/commit)        ; the docstring of a Var, without quoting it

Each helper returns a result map ({:command :exit :out :err :success? ...}) instead of throwing, so it composes in a pipeline. The ! variants throw when you want that instead. Because a session namespace carries its own *cwd* and current-session, the same helper called from the agent and from your REPL in that session resolves to the same directory.

The agent’s REPL and yours

eval_clojure does not shell out to a Clojure. It evaluates the form in this JVM, in clai.home.core by default. That namespace is seeded with helpers for exactly this situation:

;; what the agent runs, and what prints in your REPL
(help)                     ; a cheat sheet of what this namespace offers
(tools)                    ; the tool registry of the calling agent, live
(context)                  ; this session's id, model, cwd
(history)                  ; the stored messages of this session
(vars 'clai.util)          ; the Vars of a namespace in this process
(var-detail "clai.util" "error-message")

During the call, the session context is bound to *context*, so evaluated code can ask what session it is running in. Everything it defines stays: a def made by one tool call is there in the next one. And clai.home.core is an ordinary namespace in your JVM. You can in-ns into it, or name a Var fully qualified, and inspect exactly what the agent left behind.

The agent is encouraged to def values worth keeping rather than hiding them in a let, so a (def ...) appears in transcripts where you would not expect it. A def is a shared scratchpad that both of you can see.

A worked example

(new! "/home/me/code/clai")

(prompt! "Find the function that renders tool calls in the REPL, then make
          the completed status print in green.")

;; The agent reads src/clai/repl.clj, edits it, reloads the namespace, and
;; evaluates a small call to check the change. You can load and inspect the
;; same code while it is live:

(require 'clai.repl :reload)
(clojure.repl/source clai.repl/prompt!)

Nothing about that is special-cased. A file write and require ... :reload both land in the running system, which is why extending the harness is a conversation rather than a release.