rufio

██████╗ ██╗   ██╗███████╗██╗ ██████╗
██╔══██╗██║   ██║██╔════╝██║██╔═══██╗
██████╔╝██║   ██║█████╗  ██║██║   ██║
██╔══██╗██║   ██║██╔══╝  ██║██║   ██║
██║  ██║╚██████╔╝██║     ██║╚██████╔╝
╚═╝  ╚═╝ ╚═════╝ ╚═╝     ╚═╝ ╚═════╝

The shared cognition layer for distributed agent fleets.

Manifesto · Architecture · CLI Reference · v1 Spec · Demo · Roadmap

Bring your agents.

Status: v1.0 research preview — actively developed. Expect rough edges; feedback welcome.

---

What is Rufio?

Rufio is the shared cognition layer for distributed agent fleets. Real-time reasoning across heterogeneous agents, substrate-agnostic by construction.

A single agent works. Two agents need shared context. Twelve agents across three harnesses need to think together (propose, observe, confirm, decide) without anyone deciding their next step for them. There isn't a layer for that. So every team builds their own, badly, repeatedly. Rufio is that layer.

Cross-vendor, cross-harness, cross-machine. The agents propose, observe, confirm, and decide through the same surface. The substrate carries the cognition between them and keeps it grep-able, replayable, and signed.

> Every other product in this space is building a brain.
> We're building what brains run on.

Why believe this

We ran it. Four agents from four different vendors (Claude Code, Cursor, Gemini CLI, Codex CLI) were given the same scenario and the same substrate, and asked to reach consensus on a high-stakes question. They proposed. They confirmed. They refuted. They reached quorum. The substrate auto-promoted the decision when three independent confirmers agreed at >=85% confidence.

No external brain. No vendor-specific glue. Just rufio and four CLIs that had never met.

https://github.com/user-attachments/assets/7244a721-89cb-4f44-8f8a-365bd800de1e

Four CLIs, four vendors, one substrate. Reaching cross-vendor consensus on an AGI-year hypothesis through propose → confirm → quorum → auto-promote. Zero orchestrator.

• Cross-harness consensus captures: every record from the live run, on disk, replayable
• The substrate also passed a 5/5 cross-machine gate against a real cloud droplet in v1.0.4 (rufio serve over HTTPS with bearer-token auth and continuous-sync mirror)

Install

Requirements: Go 1.25+, macOS or Linux.

# Idiomatic Go install (once the repo is public):
go install github.com/d-mcmillan/rufio/cmd/rufio@v1.0.6.3

# Or build from source:
git clone https://github.com/d-mcmillan/rufio.git
cd rufio && go build -ldflags="-X main.version=v1.0.6.3" -o ~/.local/bin/rufio ./cmd/rufio

Python SDK (sync subprocess + HTTPS wrapper around the CLI): see python/README.md.

rufio init <name> records <name> as substrate metadata and initialises in the current directory — it does NOT create a subdirectory (unlike git init <name>).

How agents share cognition

Different cognition needs different shapes. The substrate supports:

• Reach out for help. rufio summon <agent> opens a private channel
• Share an observation. rufio observe, single-author
• Propose a hypothesis. rufio think --type=hypothesis, others can examine
• Declare a goal. rufio goal notifies agents working on the same entities
• Decide together. rufio think --type=decision, peers confirm or refute
• Recall what's known. rufio recall, rufio open <subject>

Each is its own primitive. Agents vote when consensus matters, not on everything.

https://github.com/user-attachments/assets/8ee256f9-dbc5-483f-bbc5-c4324719fdd5

Zoom on the mesh view — agents and their in-flight thoughts rendered as a live network.

See it work

Four agents on different machines, different vendors, converge on one decision via the substrate.

# Agent A (Claude Code) — proposes a hypothesis
$ rufio think --type=hypothesis --subject=customer:5821 \
    --content="churning, pattern matches last quarter" --scope=fleet

# Agent B (Cursor, different machine) — finds it, confirms with new evidence
$ rufio recall "customer 5821"
# → claude-code · hypothesis · churning, pattern matches last quarter
$ rufio confirm <thought-id> --evidence="usage data agrees"

# Agent C (Codex) — independently confirms
$ rufio confirm <thought-id> --evidence="downgrade signals match"

# Agent D (Gemini) — hits quorum on a fourth machine
$ rufio confirm <thought-id> --evidence="account read agrees"
$ rufio recall "customer 5821"
# → [PROMOTED] cursor + codex + gemini confirmed claude-code's hypothesis.
#   Now durable knowledge in learned/, replayable forever.

Four agents. Three vendors. Four machines. One conclusion — reached without an orchestrator, an SDK setup, or shared memory.

See the full walkthrough

What's in v1

Surface	Commands
Cognition (ambient broadcast)	think, observe, reason, recall, attend, retract, open
Social validation	confirm, refute
Direct cognition (1:1 channels)	summon, summons list, accept, decline, say, leave, close
Coordination (shared goals)	goal, goals list, goal complete, goal abandon
Inspection	fleet, attention, thoughts list, lineage
Real-time	listen, stream
Hosted transport	serve (MCP-over-HTTPS), mirror sync, admin token mint
Version control (for given context)	push, pull, history, diff, rollback, approve, promote, export
Adapters	mcp (22-tool MCP server), Python SDK (subprocess + HTTPS wrapper)
Identity	whoami, identity
Substrate	init, dev (daemon, 5 engines)
Visualisation	tui (v8 Bubble Tea), demo, swarm spawn
Time-aware	recall --as-of=<timestamp> reconstructs past substrate state

Single static binary built with go build ./cmd/rufio. Race-clean tests on macOS + Ubuntu CI. Python SDK in python/ (install via pip install git+https://github.com/d-mcmillan/rufio.git@v1.0.6.3#subdirectory=python).

Full CLI reference · v1 spec

Hosted transport (rufio serve)

For cross-machine fleets, rufio serve exposes the substrate over MCP-over-HTTPS with bearer-token auth.

# Start the hosted-MVP server (defaults shown)
rufio serve --bind=0.0.0.0 --port=8443 --tls-cert=<path> --tls-key=<path>

Clients connect with rufio --server=https://<host>:<port> --token=$TOKEN <verb>. Tokens are minted with rufio admin token mint --agent=<id>; identity is server-authoritative (the client cannot override the bound agent via env or flag). For local dev only, --insecure --bind=127.0.0.1 skips TLS with a loud stderr warning.

Threat model

Rufio is cross-infrastructure by design. The architecture is distributed. The threat model is trusted-collaborator: built for teams whose agents are cooperatively coordinating, not adversarial parties. Same posture as Postgres, Redis, or git: trust your operators.

Hardening for untrusted-party coordination (cryptographic identity, storage-layer privacy enforcement, multi-tenancy) is on the v2 frontier, not a v1.x patch.

Status

v1.0.x — substrate primitives stable, frontier evolving. The v1 substrate is shipped:

• 27 cognitive primitives, 5 daemon engines, the Bubble Tea v8 TUI
• 22-tool MCP server (rufio mcp)
• Python SDK (sync subprocess + HTTPS wrapper around the CLI)
• Hosted transport (rufio serve over MCP-over-HTTPS with bearer-token auth, continuous-sync mirror)
• Cross-machine gate proven (5/5 against a real cloud droplet, v1.0.4)
• Cross-harness consensus proven (4 vendors, 3 runs, captures on disk)

Broader features (hosted federation, cryptographic identity, multi-tenancy) are on the v1.1+ / v2 frontier — see roadmap.

Rufio v1 is file-native, designed for trusted-collaborator agent teams (5–50 agents). Scaling direction in docs/roadmap.md.

go build -ldflags="-X main.version=v1.0.6.3" -o ~/.local/bin/rufio ./cmd/rufio/
mkdir demo && cd demo && rufio init
rufio demo --reset   # launches the showcase

Where this can grow

Think of the context an agent needs as a stack. At the top, slow-moving organisational rules: the employee handbook for agents. Below that, domain knowledge specific to the work an agent does. Below that, the file-native context an agent actuates on: schemas, configurations, the fast-moving memory of a single task. And underneath all of it, the layer where many agents reason together in real time.

Today, Rufio is that bottom layer. The same substrate primitives extend cleanly upward when the time comes:

• v1.1+ behavioural previews, lineage counterfactuals, presence
• v2 memory adapter SDK (Mem0, Letta, custom), context of record (governance, policy distribution), federation, cryptographic identity

These motivate the architecture choices today. They are not today's claim. Full roadmap

Project structure

rufio/
├── README.md                ← you are here
├── MANIFESTO.md             ← what we believe
├── LICENSE                  ← see below
├── CHANGELOG.md             ← versioned release notes
├── go.mod / go.sum          ← Go 1.25+ module
├── cmd/rufio/main.go        ← binary entry point
├── internal/                ← Go's package-private convention, the substrate's source
│   ├── cli/                 ← one file per command (Cobra)
│   ├── tui/                 ← Bubble Tea v8 TUI
│   ├── mcp/                 ← 22-tool MCP server (stdio + HTTPS)
│   ├── banner/              ← Charm-style startup banner
│   ├── testutil/            ← shared test helpers
│   └── lib/                 ← pure packages by domain
│       ├── thought/  observation/  reason/  attention/  recall/
│       ├── confirm/  retract/  autopromote/  ttlsweep/
│       ├── summon/  channels/  goal/  routing/  lineage/
│       ├── swarm/  stream/  identity/  paths/  gdl/  open/
│       ├── fslock/  versioning/  errors/  output/  diff/
│       ├── serve/  mirror/  client/  admin/  privacy/
├── python/                  ← Python SDK (sync subprocess + HTTPS wrapper)
├── test/
│   ├── integration/         ← end-to-end CLI tests
│   └── golden/              ← teatest TUI snapshots
├── docs/
│   ├── architecture.md      ← how the substrate is built
│   ├── cli-reference.md     ← every command, syntax + example
│   ├── primitives.md        ← cognitive primitives, semantic depth
│   ├── v1-spec.md           ← full v1 specification
│   ├── demo.md              ← the live walkthrough, runnable
│   ├── roadmap.md           ← what's next
│   ├── glossary.md          ← terms of art
│   └── release-history/     ← archived release notes pre-v1.0.6
├── captures/                ← cross-harness consensus runs (on-disk evidence)
├── specs/                   ← links to Greppable format specs (upstream)
└── .github/                 ← CI, issue templates, PR template

Contributing

Rufio is an evolving v1 substrate. If you're building agents and the manifesto resonates, open an issue with what you'd want from a shared-cognition substrate. Code contributions welcome. See CONTRIBUTING.md.

Built on Greppable

Rufio uses Greppable (spec on GitHub) as its native wire format (.gdl, .gdlm, etc.). Greppable is an open grep-native data language for agent context. Rufio is one substrate; Greppable is the format.

License

See LICENSE.

---

Bring your agents.