Liking cljdoc? Tell your friends :D

autonomous

staging-gate release Clojars Project License: MIT

Make a running application agent-operable. The app declares, inside the running program, what an agent may do (tools) and see (resources), in its own vocabulary. A bridge serves that surface over MCP, so any MCP client (Claude Code, a hive swarm, your own agent) can drive the app: locally over stdio, or remotely over authenticated HTTP. The runtime is .cljc with a re-frame adapter; the bridge runs on the JVM, babashka and ClojureWasm.

The app does not have to be Clojure, and it does not have to open a port:

  • Any language. libautonomous is the runtime as a C library. A Rust, C, Go or Zig app declares its tools and keeps validation, scopes and the journal in process (doc/cabi.md).
  • Production without a REPL. The app dials the bridge over a websocket with a runtime token (doc/websocket.md).
  • No code change at all. An OpenAPI 3 service becomes agent tools from its spec (doc/openapi.md), and a Ring/reitit app opts routes in with route data, like a logging middleware (doc/middleware.md).
  • Many apps, one bridge. A fleet serves UI builds and services side by side, also from inside bb-mcp (doc/fleet.md).

Why

Agents that drive a UI through screenshots and clicks are slow and brittle, and they see none of the app's own meaning. Agents that get a raw REPL can do anything, which is too much. autonomous sits between the two. The app names the operations it supports, with malli schemas, scopes and descriptions. An agent calls them like any MCP tool, and the call runs through the same code path a human click does (for re-frame: a real dispatch-sync through interceptors and effects). Every call is attributed to an actor and recorded, so several agents can share one app.

Quickstart

The repository ships a re-frame todo app (example/). Run it and drive it from Claude Code. You need the Clojure CLI, Node.js and npm.

git clone https://github.com/hive-agi/autonomous && cd autonomous
npm install
clojure -M:cljs -m shadow.cljs.devtools.cli watch app

Open http://localhost:8280/. The page loads the app and its agent surface. In another terminal, register the bridge with your MCP client:

claude mcp add todo -- clojure \
  -Sdeps '{:deps {io.github.hive-agi/autonomous {:mvn/version "0.2.0"}}}' \
  -M -m autonomous.cli serve --dir "$PWD" --build app

The agent now sees todo_add, todo_toggle, todos_visible and the other app tools, plus the autonomous_* session tools. Ask it to add a todo and watch the page change. --build app matters here: without it the bridge picks the first build in shadow-cljs.edn, which is :test.

One command: bb demo

bb demo

An agent drives the todo app over MCP; the caption names each call

bb demo starts shadow-cljs (watch app) on ports next to the defaults (nREPL 7889, dev-http 8281, so your own watch on 7888/8280 keeps running), starts the bridge over loopback HTTP (http://127.0.0.1:7777/mcp, no token), and opens the page. With no display, it prints the URL instead. A scripted agent (example/demo-script.json) then makes one MCP call every 1.5 s: it adds, ticks, filters and removes todos, and sends one empty todo that the malli schema refuses. The demo also prints the commands that point Claude Code or a hive ling at the same endpoint. Ctrl-C stops everything it started.

flageffect
--no-scriptno scripted agent: bring your own
--no-openprint the URL, do not open a browser
--exitstop once the script has run
--step-ms Npause between scripted calls
--record OUT.gifrecord the GIF above with headless Playwright (doc/demo/record.py, needs pip install playwright and ffmpeg)

Your own app needs two things. First, the library on its classpath (malli comes along; re-frame and datahike stay your choice):

;; deps.edn
io.github.hive-agi/autonomous {:mvn/version "0.2.0"}

Second, a namespace that registers its surface, called from your init. This is the example's, shortened:

(ns todo.agentic
  (:require [autonomous.core :as a]
            [autonomous.re-frame :as arf]))

(defn install! [dev?]
  (a/set-app-info! {:name "todo"
                    :description "A todo list. Add with todo_add, read todos_visible."})
  (arf/reg-event-tool :todo/add
    {:description "Add a todo item. Answers the visible todos."
     :input [:map [:text [:string {:min 1 :max 200}]]]
     :args->event (fn [{:keys [text]}] [:todo/add text])
     :result-sub [:todos/visible]})
  (arf/reg-sub-tool :todos/visible
    {:description "The todos currently visible under the active filter."})
  (arf/expose-db! {:paths [[:todos] [:filter]]})
  (arf/observe-events! {:payloads? true})
  (when dev? (arf/install-dev-tools!)))

Core concepts

  • Tool: something an agent may do. A name, a description, a malli input schema (published as JSON Schema), required scopes, and a handler.
  • Resource: something an agent may read, at a URI.
  • Scope: a permission keyword. :read, :write, :admin (covers every scope) or any keyword the app invents. A request with no scopes gets #{:read}.
  • Runtime: one running program that carries the registry: a browser tab, a node process, a JVM.
  • Session: one agent's conversation with the bridge: its actor, its scopes and the runtime it is attached to.
  • Lease: one actor's exclusive right to write to a runtime for a while. Reads stay open to everyone.
  • Journal and ledger: each runtime keeps a bounded journal of calls, leases and app events. The bridge drains journals into a ledger (in memory or datahike) that agents can query.

doc/concepts.md explains each one.

Guides

guidewhat
conceptstools, resources, scopes, grants, sessions, leases, journal, ledger, actors
securityremote exposure, tokens, Origin checks, tunnels, secrets via hive-compose
swarmsmany agents on one app: spread over instances or share one under leases
fleetone bridge over many apps: UI builds and microservices, each with its own tools and nREPL
fleet demoone bridge drives the todo UI, a JVM orders service and a bb inventory service
websocketproduction: the app dials the bridge with a runtime token, no nREPL, no inbound port
any languagelibautonomous, the runtime as a C library: apps in Rust, C, Go, Zig dial the bridge and keep validation, scopes and the journal
OpenAPIan OpenAPI 3 service's operations as agent tools, with no change to the service
middlewareautonomous.ring: MCP from the app's own Ring/reitit stack, routes opted in by route data
bb-mcpan app fleet mounted inside bb-mcp, beside its own tools
babashkathe bridge on babashka (stdio and HTTP) and ClojureWasm (stdio), bb tasks, bb e2e
architecturestrata, ports and adapters, how a call travels
hivethe autonomous IAddon for hive-mcp, and hive-compose programs
releasingstaging gate, a patch release per push to main, Clojars
logothe golden-ratio construction and palette of the mark

Fleet and cheap hosts

  • Fleet: one bridge serves many apps at once (UI builds and microservices, each hosting its own autonomous tools over its own nREPL). Repeat --dir or --port, or list :targets; tools become <app>__<tool>, the session tools take a target, autonomous_apps shows each app's status, and an app that is down or slow drops out without affecting the others.
  • Backend examples: example/orders is a JVM service and example/inventory a babashka microservice, each hosting its own tools, a resource, an app-defined scope and an asynchronous tool over its own nREPL; each keeps its whole agent surface in one namespace. bb example/probe.clj drives either (or both as a fleet) through the bridge over stdio.
  • Cheap hosts: the same bridge runs on babashka (bb serve, stdio and HTTP, same security pipeline) and on ClojureWasm (stdio). bb e2e proves the swarm story live from a bb bridge.

Develop and test

clojure -M:test unit                                     # JVM suite
bb test                                                  # babashka suite
bb e2e                                                   # live swarm story from a bb bridge
bb cabi && bb cabi-rust && bb cabi-e2e                   # libautonomous, C smoke, Rust app live (needs jolt)
npm install
clojure -M:cljs -m shadow.cljs.devtools.cli compile test && node target/cljs-test/test.js

The :integration suite (clojure -M:test integration) needs live runtimes: compile and watch the :e2e build, start two node target/e2e/main.js, then run it. It proves isolation across instances, lease coordination and ledger attribution over the real nREPL channel.

Status

Experimental, on Clojars. 0.2.0 adds the websocket channel, apps in any language through libautonomous, OpenAPI tools, the Ring/reitit middleware, bb-mcp fleets and the bb demo / fleet demos. Every library change merged to main releases a patch (see releasing). Next: Go and Zig bindings, resource subscriptions, re-frame2 frames.

License

MIT. See LICENSE.

Can you improve this documentation? These fine people already did:
Pedro Gomes Branquinho & Pedro G. Branquinho
Edit on GitHub

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts
Ctrl+kJump to recent docs
←Move to previous article
→Move to next article
Ctrl+/Jump to the search field
× close