Skip to main content
Glama

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):

;; 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:

(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:

clojure -M:serve --dir ../todo          # stdio MCP, finds .shadow-cljs/nrepl.port

Register it with your MCP client, e.g. Claude Code:

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

Related MCP server: MCP-ToolHub

Plain tools and the backend

Any program that runs autonomous.core can register tools; re-frame is one adapter, not a requirement.

(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:

(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.

# 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:

: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).

;; 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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agent clients to safely connect to tools and execution resources through MCP with authorization, approvals, audit, chat-context isolation, SSH/Docker access, and long-running command session tracking.
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables secure discovery and invocation of sandboxed filesystem, repository inspection, and utility tools through a unified MCP client with schema validation, timeouts, and execution traces.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agents to access remote and local MCP servers plus HTTP APIs through a single MCP endpoint, with per-consumer scoped tokens, tool-level permissions, and encrypted secret management.
      5
      AGPL 3.0