Ruflo — Overview · Usage · Status

The complementary doc to USERGUIDE.md (deep reference) and /verification.md (cryptographic witness). This doc tells you what Ruflo is, how to use it day-to-day, and what currently works — without the encyclopedic reference depth.

Overview

Ruflo is a multi-agent AI orchestration layer for Claude Code. It turns Claude Code from a single-context coding assistant into a coordinated swarm of agents that share memory, learn from outcomes, talk across machines, and remain auditable.

The runtime is the ruflo npm package. End-user surface is:

• MCP server — exposes 300+ tools to Claude Code (memory, agents, swarm coordination, hooks, GitHub integration, browser automation, etc.).
• CLI — 49 top-level commands (ruflo agent, ruflo swarm, ruflo memory, ruflo hooks, ruflo verify, …) for terminal/script use.
• Claude Code plugins — 32 installable plugins (ruflo-core, ruflo-federation, ruflo-cost-tracker, …) that bundle agent + skill + slash-command definitions.
• WASM kernels — Rust-compiled WASM for the policy engine, embeddings, and proof system; plugged into the same MCP/CLI surface.

For the "why" — coordinated swarms, self-learning memory, federated comms, enterprise security — see README.md.

Usage at a glance

The intended day-to-day flow:

1. Install once:

   bashCopy

   npx ruflo init --wizard
   

   This writes a CLAUDE.md with hooks and routing rules, registers the MCP server with Claude Code, and seeds .claude-flow/ with config + memory.

2. Just use Claude Code normally. Hooks automatically route tasks, retrieve relevant memory patterns, and coordinate background agents. You don't have to learn the 300 MCP tools — the routing layer does.

3. Run the CLI for orchestration tasks that don't fit naturally into Claude Code:

   • ruflo agent spawn -t coder --name api-worker — long-running agent
   • ruflo swarm init --topology hierarchical --max-agents 8 — coordinated team
   • ruflo memory search --query "auth patterns" — semantic search across stored knowledge
   • ruflo doctor --fix — diagnose & repair install
   • ruflo verify — confirm your installed bytes match the signed witness

4. Install plugins as you need them:

   bashCopy

   /plugin marketplace add ruvnet/ruflo
   /plugin install ruflo-federation@ruflo
   

Full command reference: USERGUIDE.md.

Status — what currently works

Snapshot at branch fix/issues-may-1-3, last commit 52a96f3. Latest published is [email protected] on npm; the branch holds 22+ unpublished commits queued for 3.6.25.

Test baseline

Capability inventory (auto-generated via scripts/inventory-capabilities.mjs)

Recently shipped (since [email protected] published)

Audit hardening — audit_1776853149979:

• Command injection closed in github-safe.js, statusline.js/cjs (git calls), github-tools MCP (gh pr/issue/run), update/executor (npm install).
• Loader-hijack env vars (LD_PRELOAD, NODE_OPTIONS, DYLD_*) denied at the terminal_create boundary via validateEnv().
• File mode 0600 enforced on session, terminal, memory stores via fs-secure.writeFileRestricted.
• MCP stdin DoS cap (10MB) on bin/mcp-server.js + bin/cli.js to prevent un-newlined-input OOM.
• Fetch timeouts on verify + IPFS HEAD probe.

Encryption at rest — ADR-096, all 4 phases shipped:

• AES-256-GCM vault module with magic-byte format (RFE1) for backward-compat migration.
• Opt-in via CLAUDE_FLOW_ENCRYPT_AT_REST=1; off-by-default preserves the 1865-test baseline.
• High-tier stores wired: sessions/, terminals/, .swarm/memory.db (sql.js SQLite + ONNX embeddings).
• 76 dedicated tests across vault primitives, integration, tamper detection, migration paths.

Federation budget circuit breaker — ADR-097, Phase 1 shipped:

• federation_send accepts optional budget/maxHops/hopCount/spent metadata.
• Default maxHops: 8 defangs recursive delegation loops even for callers that don't opt in.
• Constant-string error reasons (HOP_LIMIT_EXCEEDED, BUDGET_EXCEEDED, INVALID_BUDGET) — no oracle leak.
• Closes #1723 (and dup #1724).

What's next

Tracked in the project task list (see GitHub Project / TaskList):

Verification

Every fix in verification.md is signed with Ed25519 keyed off the git commit. To verify your installed bytes match what was witnessed:

ruflo verify

The command fetches the manifest, recomputes SHA-256 for every cited file, re-derives the public key from the git commit, and verifies the signature. Drift in any fix produces a non-zero exit + a structured error pointing at the regressed file.

Per-capability witness signing for the full 300-tool / 49-command surface is in flight — see tasks #25 / #26.

Where to go next