rUvOS

Build

cargo build --workspace --jobs 4

🚀 Quickstart

<p align="center"> <img src="assets/quickstart.svg" alt="Four steps: clone and run ./setup.sh, restart Claude Code, verify with claude mcp list showing ruvos Connected, then just talk." width="100%"> </p>

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 52 rUvOS tools are now available to Claude Code in every project.

<details> <summary>What <code>setup.sh</code> does (10 steps, all idempotent)</summary>

1. Check prerequisites (cargo) 2. Build the release binary 3. Remove the incompatible v2/v3 npm CLI (ruflo, @claude-flow/cli) 4. Install ruvos binary → /usr/local/bin or ~/.local/bin 5. Write PATH + RUVOS_HOME to your shell profile 6. Scaffold ~/.ruvos/{plugins,sessions,cve,agents,intel} 7. Register rUvOS with Claude Code: claude mcp add ruvos --scope user 8. Wire Claude Code lifecycle hooks into ~/.claude/settings.json: - PreToolUse → pre-hook (task/edit/command routing + safety) - PostToolUse → post-hook (SONA learning, trajectory store) - Stop → session checkpoint (.rvf fork) 9. Register rUvOS with Codex CLI (~/.codex/config.json) if installed 10. Smoke-test: binary version + MCP round-trip (expects ≥52 tools)

Leaves alone: claude-flow / ruv-swarm MCP servers and any Ruflo Claude Code plugins — they coexist fine (different namespaces, processes, data dirs).

Flags: --no-mcp (skip steps 7-9) · --no-hooks (skip step 8) · --prefix DIR (install location) · --help. </details>

<details> <summary>Manual install (if you prefer)</summary>

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

RUVOS_HOME defaults to ./.ruvos; set it globally to share one memory/session store across every project. </details>

---

`plugin` — discover and run plugins

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plugin.list","arguments":{}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"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

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

// template-driven
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"orchestrate.run","arguments":{"template":"feature","task":"build POST /users"}}}
// → { "status":"completed", "planned":true, "plan_cost":4.0, "steps":["planner","coder","tester","reviewer"] }

// goal-driven (no template)
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"orchestrate.run","arguments":{"task":"harden auth","goal":{"secured":true,"tested":true}}}}
// → { "template":"custom", "planned":true, "steps":["security","coder","tester"] }

Templates: feature · bugfix · refactor · security · sparc