autonomous
by hive-agi
README.md
# autonomous
Make an application agent-operable. The app declares what an agent may **do**
(tools) and **see** (resources), in its own vocabulary, inside the running
program. A bridge exposes that surface over MCP, so any MCP client (Claude
Code, a hive swarm, your own agent) can drive the app: locally over stdio,
remotely over authenticated HTTP.
- **UI first:** a re-frame adapter turns events into tools and subscriptions
into read-only tools. Events go through re-frame, so interceptors, effects
and the screen behave exactly as when a human clicks.
- **Backend next:** the runtime core is `.cljc`. A Clojure service registers
tools the same way and is reached through its nREPL or in-process.
- **Swarm-ready:** every agent has its own identity and session. Agents spread
over an app's instances (tabs, processes) or share one under write leases.
A journal and a durable ledger (datahike) record who did what.
- **Secure by default:** scopes on every tool, least privilege when none is
granted, hashed bearer tokens, Origin checks, and a bridge that refuses a
public bind without tokens. The nREPL never leaves the machine.
```
agent(s) ──MCP──▶ bridge (JVM) ──nREPL / in-process──▶ runtime (browser tab, node, JVM)
sessions, auth, autonomous.core registry
ledger (datahike) + adapters (re-frame, ...)
```
## Quickstart: a re-frame app
Add the dependency to the app build (ClojureScript; malli comes along):
```clojure
;; deps.edn of the app, alias used by shadow-cljs
io.github.hive-agi/autonomous {:mvn/version "0.1.0-SNAPSHOT"}
```
Declare the agent surface, next to your events and subs:
```clojure
(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}]]] ; malli
:args->event (fn [{:keys [text]}] [:todo/add text])
:result-sub [:todos/visible]})
(arf/reg-sub-tool :todos/visible
{:description "The todos currently visible."})
(arf/expose-db! {:paths [[:todos] [:filter]] :redact [[:user :email]]})
(arf/observe-events! {:payloads? true}) ; journal what the human does too
(when dev? (arf/install-dev-tools!))) ; :admin-only generic dispatch/db tools
```
Call `(todo.agentic/install! goog.DEBUG)` from your init. Run the app as
usual (`shadow-cljs watch app`), open it in a browser, then start the bridge:
```sh
clojure -M:serve --dir ../todo # stdio MCP, finds .shadow-cljs/nrepl.port
```
Register it with your MCP client, e.g. Claude Code:
```sh
claude mcp add todo -- clojure -Sdeps '{:deps {io.github.hive-agi/autonomous {:mvn/version "0.1.0-SNAPSHOT"}}}' \
-M -m autonomous.cli serve --dir /path/to/todo
```
The agent now sees `todo_add`, `todos_visible` and the session tools below.
Input schemas come from your malli `:input` (as JSON Schema); arguments are
decoded leniently (`"2"` for an int, `"done"` for `:done`) and then validated,
so a wrong call is refused with a message that says what to change.
### Session tools (every server)
| tool | what |
|---|---|
| `autonomous_whoami` | actor, scopes, attached instance |
| `autonomous_runtimes` | running instances of the app (tabs, node processes) |
| `autonomous_attach` | pin this session to one instance |
| `autonomous_journal` | recent events of the instance: tool calls, leases, the human's re-frame events |
| `autonomous_ledger` | durable, queryable record across instances, reloads and agents |
| `autonomous_poll` | collect a result that is still running (async tools) |
| `autonomous_lease` / `autonomous_release` | exclusive write access for a multi-step change |
## Plain tools and the backend
Any program that runs `autonomous.core` can register tools; re-frame is one
adapter, not a requirement.
```clojure
(require '[autonomous.core :as a])
(a/reg-tool :orders/refund
{:description "Refund an order. Money moves: confirm the amount first."
:input [:map [:order-id :uuid] [:cents [:int {:min 1}]]]
:output [:map [:refund-id :uuid]]
:scopes [:billing] ; app-defined scope
:annotations {:destructiveHint true}
:handler (fn [{:keys [order-id cents]} grant]
(refund! order-id cents (:actor grant)))}) ; may return a future
```
A Clojure service is reached through its nREPL (`--clj`, port from
`.nrepl-port`), or embeds the bridge in-process with the `:local` target:
```clojure
(require '[autonomous.cli :as cli] '[autonomous.mcp.http :as http])
(http/start! (cli/build-server {:target {:target/kind :local :target/id "orders"}})
{:bind "127.0.0.1" :port 7777 :tokens tokens})
```
Extend with an open multimethod: `(defmethod autonomous.runtime.invoke/invoke-kind :my/kind ...)`
adds a tool kind; `autonomous.core/use!` adds middleware around every call;
`autonomous.bridge.channel/make` adds a transport; `autonomous.bridge.ledger/make`
adds a ledger store.
## Remote, safely
The nREPL is remote code execution by design. **It stays on the machine.**
Run the bridge next to the app and expose only the MCP endpoint, which offers
nothing but the scoped tools the app declared.
```sh
# 1. one token per agent (shown once; config stores only its SHA-256)
clojure -M:token --actor agent-1 --scopes read,write
# 2. serve MCP over HTTP with those tokens
AUTONOMOUS_TOKENS='[{:sha256 "…" :actor "agent-1" :scopes [:read :write]}]' \
clojure -M:datahike:serve --dir ../todo --http 127.0.0.1:7777 --ledger datahike --datahike-path .autonomous/ledger
# 3. reach it from elsewhere through a tunnel, not an open port
ssh -N -L 7777:127.0.0.1:7777 dev-box # or Tailscale / WireGuard
```
What the HTTP transport enforces, in order: a non-loopback bind without
tokens refuses to start; a request with a foreign `Origin` gets 403 (DNS
rebinding); a missing or unknown bearer token gets 401; a session id is
honoured only for the actor that opened it (404 otherwise). Scopes are checked
again inside the runtime, and a request carrying no scopes gets `#{:read}`.
Secrets: run the bridge itself as a hive-compose host program and let
compose inject the token entries from `pass`
(`:program/command ["clojure" "-M:serve" "--dir" "../todo" "--http" "127.0.0.1:7777"]`,
`:program/env {"AUTONOMOUS_TOKENS" {:pass "autonomous/todo/tokens"}}`), or use
any secret store that sets the variable.
## Swarms
- **Parallel:** open N instances (tabs, or `node target/e2e/main.js` for a
headless runtime). Each agent calls `autonomous_runtimes`, then
`autonomous_attach` to its own instance. No interference.
- **Shared:** agents on one instance coordinate with `autonomous_lease`: the
holder writes, everyone keeps reading, other writers get a `leased` refusal
naming the holder until release or expiry.
- **Memory:** `autonomous_ledger` answers "what did agent-3 do in the last
ten minutes", across reloads. With datahike, history is kept (`as-of`).
## hive
`hive/` is an IAddon for hive-mcp (tool `autonomous`); the core library never
depends on hive. Configure apps in `config.edn`:
```clojure
:addons {"autonomous" {:autonomous/apps
[{:app/id "todo"
:app/dir "~/PP/todo" ; finds its nREPL port file
:app/scopes [:read :write]
:app/grants {"ling-reviewer" [:read]} ; per-agent override
:app/ledger {:ledger/kind :datahike}}]}}
```
```
autonomous command=apps
autonomous command=runtimes app=todo
autonomous command=attach app=todo runtime_id=3 agent_id=<ling>
autonomous command=call app=todo tool=todo_add args={"text":"milk"} agent_id=<ling>
autonomous command=ledger app=todo actor=<ling>
```
Every hive agent gets its own session per app, keyed by `agent_id`, so a ling
swarm spreads over instances or shares one under leases, and the ledger says
which ling did what.
**hive-compose:** declare the app as a host program of a compose project
(`:program/dir "../todo"`). Compose starts `shadow-cljs watch` with its
nREPL; the program writes `.shadow-cljs/nrepl.port`; `:app/dir` (or
`--dir`) reads it. Nothing else to wire.
## Architecture
Stratified, CPPB (collect, promote, pipeline, boundary), DDD value objects in
malli, SOLID ports:
| stratum | namespaces | role |
|---|---|---|
| domain (pure, cljc) | `autonomous.domain.*` | ubiquitous language (`schema`), naming, scope algebra, leases, journal ring, wire values, tool compilation, call planning, manifest |
| runtime (cljc) | `autonomous.runtime.registry` / `invoke` / `rpc` | the only state (collect), the invocation pipeline, the EDN entry every bridge speaks (boundary, never throws) |
| adapters | `autonomous.re-frame` (+ pure `.model`) | events, subs, app-db, event origin |
| bridge (JVM) | `autonomous.bridge.*` | ports (`IRuntimeChannel`, `IRuntimeDirectory`, `ILedger`), nREPL and local channels, sessions, auth, client pipeline, ledgers |
| MCP | `autonomous.mcp.*` | pure JSON-RPC mapping, built-in session tools, stdio and HTTP transports |
| entry | `autonomous.config`, `autonomous.cli` | collect + promote config, serve |
The decision about a call (`autonomous.domain.decision/plan-call`) is a pure
function of a registry snapshot, the args, the grant and the time; app tools
and built-in tools go through the same plan.
## Develop and test
Tests run in warm REPLs (hive-test trifectas: golden, property, mutation).
The ClojureScript side needs `npm install` once (React for reagent, `ws` for
the node REPL runtime).
```clojure
;; JVM suite (aliases :test:nrepl)
(clojure.test/run-all-tests #"autonomous\..*-test")
;; ClojureScript suite (aliases :cljs:nrepl), then `node target/cljs-test/test.js`
(shadow.cljs.devtools.server/start!) (shadow.cljs.devtools.api/compile :test)
```
Run the live e2e: `(shadow.cljs.devtools.api/watch :e2e)`, start two
`node target/e2e/main.js`, then run `autonomous.e2e.live-test` (kaocha
`:integration`). It proves isolation across instances, lease coordination and
ledger attribution over the real nREPL channel.
## Status
Experimental (0.1.0-SNAPSHOT). Next: a websocket channel the page dials out on
(production, no nREPL), resource subscriptions, a Playwright-backed visual
check tool via hive-cljs, re-frame2 frames.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues