ψ Psi — A Clojure AI Agent

A self-evolving AI coding agent built in Clojure. Statechart-driven, EQL-queryable, extensible. Inspired by pi-mono.

Values

• Extensions can completely customise the agent.
• Everything is introspectable
• AI provider agnostic
• Minimal builtin behaviour

---

Quick Start

Requirements

• Java 22+ (Java 25 recommended) — the TUI requires the Java FFM API
• Babashka — for the launcher

Installation

Install the latest release:

bbin install org.hugoduncan/psi --as psi --mvn/version LATEST

Install a specific release (recommended for reproducible environments):

bbin install org.hugoduncan/psi --as psi --mvn/version 0.1.2123

Check the installed version:

psi --version
# psi 0.1.2123

Upgrade to the latest release:

bbin uninstall psi
bbin install org.hugoduncan/psi --as psi --mvn/version LATEST

Repo-local / development alternative:

bbin install . --as psi

Releases are tagged vMAJOR.MINOR.PATCH on the releases page. See CHANGELOG.md for what changed in each release.

Each release is also published to Clojars as org.hugoduncan/psi. Released startup now uses jar-owned release metadata packaged inside that artifact to construct psi’s shipped runtime basis, instead of reconstructing psi’s own runtime closure from repo-local component layout. Extensions still layer additively on top. Force a specific resolution strategy with PSI_LAUNCHER_POLICY (jar | installed | development); see doc/cli.md.

Then run psi directly:

# Bare console
psi

# Terminal UI
psi --tui

# RPC mode
psi --rpc-edn

For CLI flags, launcher-only flags, environment variables, and switch behavior, see:

• doc/cli.md

Migration note

Old alias-based startup is now non-canonical:

clojure -M:psi           -> psi
clojure -M:psi --tui     -> psi --tui
clojure -M:psi --rpc-edn -> psi --rpc-edn

Development contributors may still use repo-local invocation paths during transition, and may set PSI_LAUNCHER_POLICY=development when they want launcher basis construction to use repo-local roots. The launcher-owned psi command remains the primary operator-facing startup surface.

Emacs UI usage

For keybindings, rendering behavior, reconnect semantics, and developer checks, see:

• doc/emacs-ui.md

TUI usage

For TUI login flow, in-session commands, and runtime behavior, see:

• doc/tui.md

Built-in Tools

read bash edit write psi-tool

psi-tool is the live runtime introspection/modification tool with canonical action-based requests:

• query — EQL graph reads
• eval — in-process ψ namespace-scoped Clojure eval
• mutate — invoke registered runtime mutations with structured success/error reports
• reload-code — explicit namespace/worktree code reload with distinct reload and graph-refresh reporting
• project-repl — managed project REPL status/start/attach/stop/eval/interrupt operations with structured reports
• scheduler — delayed one-shot work via explicit create|list|cancel, including both delayed same-session prompts and delayed fresh top-level session creation
• operation — list and invoke registered deterministic operations via explicit list|invoke; list returns each operation's id and description (sorted by id), invoke runs operation-id with an EDN-map args (default {}) and returns the tagged result with every top-level key rendered (each value pr-str'd, truncated to 2000 chars). Side-effecting operations are invokable.

See:

• doc/psi-project-config.md for query/mutate/reload examples and worktree-authoritative reload targeting rules, including the recommended self-reload loop
• doc/graph-surface.md for graph discovery, root-queryable attrs, and session inventory discovery surfaces
• doc/scheduler.md for scheduler kinds, session-config support, status semantics, and introspection attrs
• doc/operations.md for the deterministic-operation list/invoke request shapes, params, all-key + 2000-char truncation rendering, and error surfacing (both the psi-tool action and the /operations / /operation commands)

Workflows

For user-facing workflow usage, workflow file location, /delegate, reload behavior, and workflow-run retention/cleanup behavior, see:

• doc/workflows.md

Workflow runs now automatically retain only the newest retained terminal runs per originating session. By default psi keeps 1 retained terminal workflow run per originating session, configurable via [:config :completed-workflow-run-retention-count]. When older retained terminal runs are removed, their linked workflow-owned child-session trees are also cleaned up.

Model controls

Psi includes Claude Opus 4.8 (claude-opus-4-8) in the Anthropic model catalog. Interactive sessions support /speed for provider throughput-tier selection and /effort for provider reasoning-effort override. Named session profiles can bundle reusable model/thinking/speed/effort settings for interactive selection (/session-profile) and workflow steps (:session-profile); see doc/tui.md, doc/configuration.md, and doc/workflows.md.

Extension API

For extension-facing runtime/query details (including memory durability operations and mid-conversation system-message injection), see:

• doc/extension-api.md

This includes the preferred workflow public-data display convention for workflow-backed extensions.

Extension install manifests

For the deps-shaped extensions.edn install model, launcher-owned startup basis construction, concise psi-owned manifest syntax, apply semantics, and introspection fields, see:

• doc/extensions-install.md

Note: extension slash commands now route implicit extension query/mutate calls through the active session that invoked the command. Explicit query-session / mutate-session helpers remain the preferred surface for cross-session or delayed/background extension work.

For built-in extension docs (extensions/ per-project local roots), see:

• doc/extensions.md

Project-local extension/config examples in this repo include:

• .psi/extensions.edn
• .psi/commit-checks.edn
• bb commit-check:rama-cc
• bb commit-check:file-lengths
• bb commit-check:dispatch-architecture

Architecture

For architecture overview, components, EQL introspection guidance, and roadmap, see:

• doc/architecture.md

Graph discovery

For the session-root graph discovery surface (:psi.graph/*), canonical discovery workflow, and graph semantics, see:

• doc/graph-surface.md

For prompt lifecycle introspection summaries and normalized prompt-turn attrs, see:

• doc/architecture.md

Configuration

Config file locations, precedence (session > project-local > project-shared > user > system), settings reference, runtime scoped setters, outbound model API proxy environment variables, and custom provider setup:

• doc/configuration.md
• doc/custom-providers.md

ψ Psi project config

Project query/config tool details:

• doc/psi-project-config.md

Project nREPL

For direct project-local REPL support distinct from psi's own runtime nREPL, see:

• doc/project-nrepl.md

References

• pi-mono — inspiration
• charm.clj — TUI framework
• Fulcrologic statecharts
• Pathom3
• nucleus