ruvos

What is this?

Out of the box, an AI coding assistant forgets everything between sessions, works alone, and leaves no trace of why it did what it did. rUvOS fixes that.

It's a single small program you run once. After that, your assistant (Claude Code, Codex CLI, Gemini CLI) can remember decisions across days, resume exactly where it left off, spin up a team of specialist agents, scan dependencies for known vulnerabilities, coordinate across terminals, and keep a signed, tamper-evident log of everything — all stored on your own disk.

It connects through the Model Context Protocol (MCP) — the standard way tools talk to AI assistants — so you don't learn new commands. You just talk, and the assistant calls the right rUvOS tool for you.

It's one static Rust binary: no Node.js, no background service, no external database, no cloud account. (The offline CVE advisory database is SQLite via rusqlite-bundled — the only native dependency, compiled in.)

The tagline: RuVector is the kernel, rUvOS is the shell. RuVector is the self-learning vector + graph + crypto substrate; rUvOS is the orchestration layer that turns it into tools your assistant can use.

🙏 Built on the work of rUv (Reuven Cohen / @ruvnet)

rUvOS consolidates and re-implements rUv's ecosystem — Ruflo / claude-flow, RuVector, the .rvf format, SONA, ruv-swarm, and more — into one Rust binary. The hard, original ideas are his. Huge thanks and full credit to rUv. 🚀

⚠️ Not compatible with the Ruflo v2/v3 npm CLI. rUvOS v4 is a clean-room Rust rewrite; there's no migration path. Running ./setup.sh uninstalls that old npm CLI but leaves your claude-flow / ruv-swarm MCP servers and plugins alone — they coexist fine (separate namespaces, processes, and data dirs).

✨ Highlights

• 🧠 Memory that lasts — store facts and recall them by meaning. Hybrid search (dense HNSW + BM25 keywords) with a temporal knowledge graph and a feedback loop that learns which results were useful.
• 💾 Resumable, signed sessions — each work context is a signed .rvf file you can return to days later; fork branches one before a risky change with full cryptographic lineage.
• 👥 A team of agents — spawn 12 specialist archetypes (coder, tester, security, …); a GOAP A* planner computes the pipeline for your goal, and failed steps retry or stop.
• 🔍 CVE / vulnerability scanning — scan any JS/TS or Rust project for known vulnerabilities via the OSV database; outputs JSON, SARIF 2.1.0 (GitHub Code Scanning), or a terminal table. Offline mode uses a local SQLite advisory database.
• 🛡️ Safety + provenance built in — risky actions are risk-checked before they run, and every action lands in a signed audit log you can verify.
• 📡 Multi-terminal coordination — independent Claude Code instances discover and message each other through plain files; no daemon, no port, no database. The optional ruvos daemon watch relay listener processes tasks dispatched from the relay bus and stores results back into memory.
• ⚡ Agent execution bridge (ADR-015) — ruvos_agent_exec closes the "markdown-only" gap: agents can now write files, run shell commands, and perform git operations directly, with optional OS-level sandbox isolation.
• 🗜️ Context compression — trim large JSON, log, code, and text payloads; originals are stored in signed session files when needed, with a replayable regression suite.
• 🔁 Learning signals — successful outcomes feed memory and intent stores so future routing improves without a second memory system.

🚀 Quickstart

git clone https://github.com/dgdev25/ruvos.git
cd ruvos
./setup.sh

Then restart Claude Code (it loads MCP servers at startup), open a new terminal, and confirm:

claude mcp list           # ruvos: ✓ Connected
ruvos --version           # ruvos 4.0.0-rc.1

That's it — all 60 rUvOS tools are now available to Claude Code in every project.

cargo build --release -p ruvos-cli
cp target/release/ruvos ~/.cargo/bin/ruvos
export RUVOS_HOME="$HOME/.ruvos"
claude mcp add ruvos --scope user -- ruvos mcp serve
claude mcp list   # ruvos: ✓ Connected

🧭 How it works

You don't type commands or keywords. Once the MCP server is connected, Claude Code sees the 60 tools and decides which to call from what you ask. The loop:

You ask in plain language; rUvOS recalls relevant past decisions, a planner computes the agent pipeline for the goal, the agents run (a failed step retries or stops the pipeline), and the outcome is learned — sharpening the next recall and plan. Underneath every step, a safety gate vets risky actions and a signed audit log records what happened.

💡 Say "rUvOS" in your request. If you also run claude-flow or ruv-swarm, naming rUvOS explicitly — "use rUvOS to…", "have rUvOS remember…" — reliably routes to it.

💡 A real session

You:  Use rUvOS to build a POST /users endpoint with validation, and remember
      the design as we go.

Claude:
  → ruvos_session_create    { name: "users-endpoint" }
  → ruvos_memory_store      { key: "spec", value: "POST /users, zod validation, …" }
  → ruvos_orchestrate_run   { template: "feature", task: "POST /users with validation" }
        planner → coder → tester → reviewer   (each leaves a real artifact)

[next day]
You:  Resume my rUvOS session for the users endpoint.
Claude:
  → ruvos_session_resume    { session_id: "…" }   # context restored from signed .rvf
  → ruvos_memory_search     { query: "users endpoint design" }

🔍 CVE Scanning

rUvOS ships a first-class vulnerability scanner for JS/TS and Rust projects (package-lock.json, pnpm-lock.yaml, yarn.lock, Cargo.lock) — callable from Claude Code via the ruvos_gov_cve_lookup MCP tool, or directly from the CLI:

# Terminal output (default — sorted by severity)
ruvos cve scan /path/to/project

# JSON — machine-readable full ScanResult
ruvos cve scan --json /path/to/project

# SARIF 2.1.0 — upload to GitHub Code Scanning
ruvos cve scan --sarif /path/to/project > results.sarif

# CI gate — exit non-zero if any High+ vuln found
ruvos cve scan --fail-on high /path/to/project

# Prod only, offline, minimum severity threshold
ruvos cve scan --prod-only --offline --min-severity medium /path/to/project

Supported lockfiles: package-lock.json (npm v1/v2/v3), npm-shrinkwrap.json, pnpm-lock.yaml (v5/v6/v9), yarn.lock (v1 + Berry/v2+), Cargo.lock (crates.io ecosystem; direct deps classified from Cargo.toml).

Data sources:

• Online: OSV API batch queries, results cached at $RUVOS_HOME/cve/osv-cache.json (30-min TTL)
• Offline: SQLite advisory database (--offline-db <path>) compatible with the cve-lite-cli schema; semver range matching (introduced ≤ version < fixed)

All flags: --json · --sarif · --prod-only · --offline · --offline-db <PATH> · --min-severity {low,medium,high,critical} · --fail-on {low,medium,high,critical} · --no-cache

📚 Complete Feature Reference

Two surfaces: CLI commands you run in a terminal, and MCP tools Claude Code calls for you once the server is connected. Both drive the same persistent state under $RUVOS_HOME (default ./.ruvos).

Part 1 — CLI commands (ruvos <command>)

Run ruvos <command> --help for the full flag list of any command.

Part 2 — MCP tools (60 tools, called by Claude Code)

In normal use you never type these — you ask in plain language and Claude Code picks the tool. To call one directly for testing, wrap it with the transport boilerplate:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '<the call line below>' \
| ruvos mcp serve

Tool names are ruvos_<domain>_<action> (e.g. ruvos_memory_store). Copy them verbatim — there is no dot-notation alias.

memory (4) — persistent semantic memory + knowledge graph

Hybrid retrieval (dense HNSW + BM25, fused), MMR diversity, recency weighting, temporal knowledge graph, and a feedback loop. Survives restarts (persisted to $RUVOS_HOME/memory.json).

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ruvos_memory_store","arguments":{"key":"db","value":"postgres pooling via pgbouncer","namespace":"proj","tags":["infra"]}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ruvos_memory_search","arguments":{"query":"database connection","namespace":"proj","top_k":5}}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ruvos_memory_retrieve","arguments":{"key":"db","namespace":"proj"}}}

session (3) — resumable, signed work contexts

Sessions are signed .rvf containers (HMAC-SHA256 + SHAKE-256 witness chain). Forking creates a COW branch with cryptographic lineage proof.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ruvos_session_create","arguments":{"name":"users-endpoint","state":{"branch":"feat/users"}}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ruvos_session_resume","arguments":{"session_id":"6305…"}}}

agent (4) — spawn, track, message, and execute

12 archetypes: coder · reviewer · tester · researcher · architect · planner · security · perf · devops · data · docs · coordinator — 9 composable traits: backend · frontend · mobile · cloud · db · ml · tdd · domain · audit

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ruvos_agent_spawn","arguments":{"archetype":"coder","prompt":"write POST /users","model":"claude-haiku-4-5","traits":["backend"]}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ruvos_agent_status","arguments":{}}}

hooks (3) — safety, routing, learning

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ruvos_hooks_pre","arguments":{"kind":"command","payload":{"command":"rm -rf /important"}}}}
// → { "blocked":true, "safety":{ "passed":false, "violations":[…] } }
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ruvos_hooks_route","arguments":{"task":"audit auth for injection"}}}
// → { "archetype":"security", "model":"claude-opus-4-8", "tier":3, "confidence":0.91 }

intel (5) — SONA trajectory + intent learning

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ruvos_intel_pattern_store","arguments":{"trajectory":["read schema","write migration"],"outcome":"success"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ruvos_intel_repo_inspect","arguments":{"path":"."}}}

plugin (2) — discover and run plugins

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ruvos_plugin_list","arguments":{}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ruvos_plugin_invoke","arguments":{"plugin_name":"my-plugin","command":"build","args":["--release"]}}}

Plugin layout (drop into .ruvos/plugins/<name>/ or ~/.ruvos/plugins/<name>/):

<name>/
├── plugin.toml        # name, version, description
├── agents/*.md        # Claude Code agent definitions (YAML frontmatter)
├── skills/*/SKILL.md  # Claude Code skills
└── commands/*.md      # slash commands

Installing plugins (ADR-040) — fetch, verify, and unpack a plugin tarball in one step:

ruvos plugin install demo --from https://example.com/demo.tar.gz   # or a local path

A .sha256 sidecar next to the tarball is required; an HMAC-SHA256 .sig sidecar is verified when RUVOS_PLUGIN_KEY is set. Publishing convention:

tar -czf demo.tar.gz -C plugin-dir . && sha256sum demo.tar.gz > demo.tar.gz.sha256

gov (12) — health, CVE scanning, audit, swarm governance

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ruvos_gov_health","arguments":{}}}
// → { "status":"ok", "tool_count":60, "persisted":{…}, "safety":{"score":1.0} }
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ruvos_gov_cve_lookup","arguments":{"project_path":"/path/to/project","format":"json","min_severity":"high"}}}
// → { "status":"clean"|"vulnerable", "finding_count":N, "highest_severity":"…", "fix_count":N }
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ruvos_gov_events","arguments":{"event_type":"agent.spawned","limit":20}}}

gov issues (6) — built-in issue tracker (beads_rust)

A lightweight issue tracker persisted in $RUVOS_HOME, with dependency edges between issues.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ruvos_gov_issue_create","arguments":{"title":"flaky parallel tests","priority":"high"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ruvos_gov_issue_list","arguments":{"status":"open"}}}

relay (6) — cross-instance coordination

Two rUvOS instances sharing one RUVOS_HOME discover and message each other via plain JSON file mailboxes (no daemon, no port). Every coordination action is recorded in the signed audit log.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ruvos_relay_announce","arguments":{"summary":"backend: auth endpoints"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ruvos_relay_list","arguments":{"scope":"machine"}}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ruvos_relay_send","arguments":{"to":"ruvos-daemon","body":"{\"method\":\"exec\",\"correlation_id\":\"t1\",\"params\":{\"ops\":[{\"op\":\"run_command\",\"cmd\":\"npm\",\"args\":[\"test\"]}]}}"}}}

Named-agent presence — relay::announce_as(id, summary) writes a presence file under a stable name (e.g. ruvos-daemon) instead of the ephemeral process UUID, so relay_send can resolve it by name across sessions.

agent_exec — execution bridge (ADR-015)

ruvos_agent_exec closes the agent "markdown-only" gap: agents can now write files, run shell commands, perform git operations, and optionally isolate all work in a fresh OS-level temp directory.

// write a file, run tests, commit — all in one call
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ruvos_agent_exec","arguments":{
  "ops":[
    {"op":"write_file","path":"src/lib.rs","content":"…"},
    {"op":"run_command","cmd":"cargo","args":["test"]},
    {"op":"git_op","git_op":"commit","message":"feat: add impl"}
  ]
}}}

// sandbox mode — all paths relative to a fresh temp dir (nothing touches the host tree)
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ruvos_agent_exec","arguments":{
  "sandbox":true,
  "ops":[{"op":"run_command","cmd":"make","args":["build"]}]
}}}

Ops: write_file · read_file · run_command (with optional cwd) · git_op (add · commit · status · diff). Pipeline stops on the first non-zero exit code.

ruvos daemon watch — relay inbox listener

A persistent background process that polls the relay bus and dispatches tasks to ruvos_agent_exec. Results are stored in memory namespace daemon so any instance can read them.

ruvos daemon watch                        # listens on "ruvos-daemon" inbox
ruvos daemon watch --agent-id my-agent    # custom inbox name
ruvos daemon watch --poll-ms 100          # faster polling

Send tasks from any Claude Code session:

// fire-and-forget exec via relay
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ruvos_relay_send","arguments":{
  "to":"ruvos-daemon",
  "body":"{\"method\":\"exec\",\"correlation_id\":\"build-1\",\"params\":{\"ops\":[{\"op\":\"run_command\",\"cmd\":\"cargo\",\"args\":[\"build\"]}]}}"
}}}

// read result from memory once the daemon has processed it
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ruvos_memory_retrieve","arguments":{"key":"daemon/results/build-1","namespace":"daemon"}}}

ruvos status — live system view

A read-only, human-facing snapshot of everything the MCP tools know: health, active swarm + members, agents, recent events, relay instances. Pure presentation over the same handlers the MCP tools use, so the CLI and MCP can never disagree (ADR-039). Add --json for the raw merged JSON.

ruvos status          # human view
ruvos status --json   # raw merged JSON for scripting

rUvOS system status

── Health ──────────────────────────────
  status: ok  version: 4.0.0-rc.1  pid: 12345  tools: 60
  data root: /home/you/.ruvos
  persisted: 2 session(s), 7 memory entr(ies), 1 agent(s), 0 intel pattern(s)

── Swarm ──────────────────────────────
  no active swarm

── Agents ──────────────────────────────
  none

── Recent events ──────────────────────────────
  2026-06-12T09:09:38Z  agent.status.listed  agent: -

── Relay instances ──────────────────────────────
  none

orchestrate — planned multi-agent pipelines

A GOAP (A*) planner computes the archetype sequence from a template or a goal + capabilities. Optional max_retries loops a failed step back for bounded rework. Templates: feature · bugfix · refactor · security · sparc.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ruvos_orchestrate_run","arguments":{"template":"feature","task":"build POST /users"}}}
// → { "status":"completed", "planned":true, "plan_cost":4.0, "steps":["planner","coder","tester","reviewer"] }
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ruvos_orchestrate_run","arguments":{"task":"harden auth","goal":{"secured":true,"tested":true}}}}
// → { "template":"custom", "planned":true, "steps":["security","coder","tester"] }

compress (1) — context compression

Trims large JSON, log, code, and text payloads before they re-enter context. When session_id is provided, the original is stored in the signed .rvf session; the returned original_ref is later retrievable via {"retrieve_ref":"<ref>"}.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ruvos_compress_run","arguments":{"content":"…large payload…","kind":"auto","session_id":"6305…"}}}
// retrieve the original later
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ruvos_compress_run","arguments":{"retrieve_ref":"a1b2c3…"}}}

Regression testing from the CLI: ruvos eval compress [--write reports/baseline.json | --compare-to reports/baseline.json].

swarm (13) — multi-agent topology lifecycle

Durable swarms with topology (hierarchical/mesh/hybrid/adaptive), members, heartbeats, and learned policy. State is cross-process locked and atomically persisted.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ruvos_swarm_create","arguments":{"objective":"ship auth","topology":"hierarchical","members":[{"agent_id":"w1","role":"coder"}]}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ruvos_swarm_assign","arguments":{"agent_id":"w1","task_id":"t1"}}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ruvos_swarm_status","arguments":{}}}

🏗️ Architecture

rUvOS is two layers in one binary: a thin orchestration shell (8 Rust crates, ~24k LOC) on top of the RuVector kernel + substrate (pure-Rust vector search, learning, graph, crypto, planning, and coordination).

Disk is the source of truth. All state persists under $RUVOS_HOME (default ./.ruvos) — redb is the fast working store, .rvf containers are signed tamper-evident snapshots, and memory.json / intel.json / agents.json are the durable JSON stores readable across processes.

$RUVOS_HOME/
├── rvf/<id>.rvf           # signed, witness-chained session containers
├── store.redb             # redb live store: agents, tasks, events, messages, metrics
├── memory.json            # memory entries (namespace → key → entry)
├── memory-graph.json      # temporal entity co-occurrence graph
├── intel.json             # SONA trajectory patterns
├── intent.json            # stable preferences and goals
├── agents.json            # agent registry
├── agents/<id>/output.md  # agent work artifacts
├── swarm.json             # swarm topology + policy
├── cve/
│   └── osv-cache.json     # OSV query cache (30-min TTL)
└── .rvf-key               # per-install signing key (0600; gitignored — never commit)

The 8 rUvOS crates

Plus 15 RuVector substrate crates (HNSW, SONA, GOAP, redb store, .rvf crypto, RuLake, swarm transport, memory graph, skills pack, safety, and more) — 23 workspace members total, all building cleanly with zero warnings. (Substrate crates with no member consumers were dropped from the build; their sources remain in substrate/.)

MCP transport

• Protocol: JSON-RPC 2.0 (custom implementation, ~500 LOC)
• I/O: tokio stdin/stdout
• Handshake: initialize → notifications/initialized → tools/list → tools/call
• Stateless server: No in-memory state; all persistence is disk-backed — process restarts are transparent

Session + signing

.rvf containers carry a payload (JSON state) plus a witness object: an HMAC-SHA256 signature over the JSON bytes. Forking extends the parent's witness chain with the new action hash, producing a cryptographic lineage proof. Signing key lives at $RUVOS_HOME/.rvf-key (generated on first use; never committed).

Hook kinds (8 total)

task.pre · task.post · edit.pre · edit.post · command.pre · command.post · session.pre · session.post

🩺 Status

v4.0.0-rc.1 — production-grade. 60 MCP tools, 455 tests passing in ruvos-mcp, zero compiler/clippy warnings across the entire 23-crate workspace, and a deterministically green cargo test --workspace (standing zero-defect policy).

Honest scope notes:

• Vector ranking uses TF cosine similarity + HNSW + RuLake (real, working algorithms); neural embeddings are feature-hashing today — a provider API can be swapped in behind the same interface.
• .rvf signing is HMAC-SHA256 + SHAKE-256 witness chains (real and verified); the full distributed witness-chain federation is deferred to v2.
• The agent runner is optional; without RUVOS_AGENT_RUNNER set, agents produce real artifacts and report success by default.
• Gemini CLI adapter: architecture ready (same CliHost trait), implementation deferred.
• Local LLM inference (ruvllm): excluded from workspace (pulls candle/hf-hub), deferred to v2 per the no-local-inference decision.

🛠️ Development

# Build
cargo build --workspace --jobs 4

# Zero-defect gate (full workspace — use --jobs 4 to avoid OOM on 30+ crates)
cargo build --workspace --jobs 4
cargo clippy --workspace --all-targets --jobs 4 -- -D warnings
cargo test --workspace --jobs 4
cargo fmt --check

# Or via just
just build
just clippy
just test
just fmt
just doctor           # ruvos doctor --strict
just contracts-check  # validate contract-manifest.json

Enforced rules (see CLAUDE.md): zero-defect workspace at all times including vendored substrate; every .rs file ≤ 500 lines; new MCP tools require an ADR explaining which tool they replace or what domain gap they fill.

Architecture decisions are recorded as ADRs in docs/spec/. The live tool/archetype/hook contract is generated into docs/contracts/contract-manifest.json and verified by just contracts-check.

📄 License

MIT — consistent with the upstream rUvnet projects. Thank you, rUv. 🙏