Ruflo: An agent meta-harness for Claude Code and Codex

Ruflo, an agent meta-harness built by rUv and powered by Cognitum.One, adds 100+ specialized agents, coordinated swarms, self-learning memory, federated comms across machines, and enterprise security guardrails to Claude Code and Codex. The tool, previously called Claude Flow, can be installed via a CLI (`npx ruflo init`) for full functionality including 98 agents, 60+ commands, 30 skills, MCP server, hooks, and daemon, or as a plugin with limited features.

Agent = Model + Harness.The model writes; the harness gives it tools, memory, loops, sandboxes, and controls so it can actually work.Ruflo is the harness— the execution layer around Claude Code and Codex that adds 100+ specialized agents, coordinated swarms, self-learning memory, federated comms across machines, and enterprise security guardrails. So agents don't just run, they collaborate. One npx ruflo init gives Claude Code a nervous system: agents self-organize into swarms, learn from every task, remember across sessions, and — with federation — securely talk to agents on other machines without leaking data. You keep writing code. Ruflo handles the coordination. php Self-Learning / Self-Optimizing Agent Architecture User -- Ruflo CLI/MCP -- Router -- Swarm -- Agents -- Memory -- LLM Providers ^ | +---- Learning Loop <-------+ New to Ruflo?You don't need to learn 314 MCP tools or 26 CLI commands. After init , just use Claude Code normally — the hooks system automatically routes tasks, learns from successful patterns, and coordinates agents in the background. 📖 Background — where the name comes from Claude Flow is now Ruflo — named by , who loves Rust, flow states, and building things that feel inevitable. The "Ru" is the rUv. The "flo" is working until 3am. Underneath, powered by rUv agentic architecture, running a supercharged Rust-based AI engine, embeddings, memory, and plugin system. Cognitum.One There are two different install paths with very different surface areas. Pick based on what you need 1744 : Claude Code Plugin | CLI install npx ruflo init | | |---|---|---| | What it gives you | Slash commands + a few skills + agent definitions per-plugin | Full Ruflo loop — 98 agents, 60+ commands, 30 skills, MCP server, hooks, daemon | | Files in your workspace | Zero | .claude/ , .claude-flow/ , CLAUDE.md , helpers, settings | | MCP server registered | No memory store , swarm init , etc. unavailable to Claude | Yes | | Hooks installed | No | Yes | | Best for | Try a single plugin's commands without committing to the full install | Production use — everything works as documented | Add the marketplace /plugin marketplace add ruvnet/ruflo Install core + any plugins you need /plugin install ruflo-core@ruflo /plugin install ruflo-swarm@ruflo /plugin install ruflo-rag-memory@ruflo /plugin install ruflo-neural-trader@ruflo This adds slash commands and agent definitions only. The Ruflo MCP server is NOT registered, so memory store , swarm init , agent spawn , etc. won't be callable from Claude. For the full loop, use Path B below. 🔌 All 35 plugins | Plugin | What it does | |---|---| ruflo-core | ruflo-swarm ruflo-autopilot ruflo-loop-workers ruflo-workflows ruflo-federation | Plugin | What it does | |---|---| ruflo-agentdb | ruflo-rag-memory ruflo-rvf ruflo-ruvector — GPU-accelerated search, Graph RAG, 103 tools https://npmjs.com/package/ruvector ruvector ruflo-knowledge-graph | Plugin | What it does | |---|---| ruflo-intelligence | ruflo-graph-intelligence ruflo-daa ruflo-ruvllm ruflo-goals | Plugin | What it does | |---|---| ruflo-testgen | ruflo-browser ruflo-jujutsu ruflo-docs | Plugin | What it does | |---|---| ruflo-security-audit | ruflo-aidefence | Plugin | What it does | |---|---| ruflo-adr | ruflo-ddd ruflo-sparc ruflo-metaharness guide /ruvnet/ruflo/blob/main/docs/metaharness-user-guide.md ruflo-arena | Plugin | What it does | |---|---| ruflo-migrations | ruflo-observability ruflo-cost-tracker | Plugin | What it does | |---|---| ruflo-agent | ruflo-plugin-creator | Plugin | What it does | |---|---| ruflo-iot-cognitum | ruflo-neural-trader — AI trading with 4 agents, backtesting, 112+ tools https://npmjs.com/package/neural-trader neural-trader ruflo-market-data macOS / Linux / WSL / Git-Bash: One-line install POSIX shells only — see Windows note below curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash All platforms including native Windows PowerShell / cmd : Interactive setup wizard — runs identically on every platform npx ruflo@latest init wizard Quick non-interactive init npx ruflo@latest init Or install globally npm install -g ruflo@latest 💡 Windows users:the curl ... | bash form needs a POSIX shell Git-Bash, WSL, MSYS . The npx ruflo@latest init wizard line works natively in PowerShell and cmd. If you hit an 'bash' is not recognized error, use the npx line instead — both end up running the same init flow. Add Ruflo as an MCP server in Claude Code canonical form, matches USERGUIDE.md claude mcp add ruflo -- npx ruflo@latest mcp start | Capability | Description | |---|---| 🤖 100+ Agents | Specialized agents for coding, testing, security, docs, architecture | 📡 Comms Layer | Zero-trust federation — agents across machines/orgs discover, authenticate, and exchange work securely | 🐝 Swarm Coordination | Hierarchical, mesh, and adaptive topologies with consensus | 🧠 Self-Learning | SONA neural patterns, ReasoningBank, trajectory learning | 💾 Vector Memory | HNSW-indexed AgentDB — measured ~1.9x faster at N=20k, ~3.2x–4.7x at N=5k vs brute force recall@10 ~0.99 ; ANN wins above the crossover, ties/loses at small N. See scripts/benchmark-intelligence.mjs | Background Workers Plugin Marketplace Multi-Provider Security Agent Federation MetaHarness /ruvnet/ruflo/blob/main/docs/metaharness-user-guide.md ruflo eject turns a ruflo project into a standalone agent toolkit with its own name. Full guide /ruvnet/ruflo/blob/main/docs/metaharness-user-guide.md . Web UI Beta https://flo.ruv.io/ RuFlo Research https://goal.ruv.io/ /agents https://goal.ruv.io/agents Web UI Beta — self-hostable, hosted demo at flo.ruv.io https://flo.ruv.io/ RuFlo's web UI is a multi-model AI chat with built-in Model Context Protocol MCP tool calling. Talk to Qwen, Claude, Gemini, or OpenAI while RuFlo invokes the same MCP tools the CLI uses — agent orchestration, persistent memory, swarm coordination, code review, GitHub ops — directly from chat. No install, no API key needed to try it. | What it is | Why it matters | | |---|---|---| | 🧠 | Any model, local or remote | 6 curated frontier models out-of-the-box — Qwen 3.6 Max default , Claude Sonnet 4.6, Claude Haiku 4.5, Gemini 2.5 Pro, Gemini 2.5 Flash, OpenAI — via OpenRouter. Add your own: any OpenAI-compatible endpoint vLLM, Ollama, LM Studio, Together, Groq, self-hosted . | | 🦾 | ruvLLM self-learning AI | Native support for ruvnet/RuVector/examples/ruvLLM — RuFlo's self-improving local model layer. Routes to MicroLoRA adapters, learns from your trajectories via SONA, and stays on your machine. Pair with the cloud models or run fully offline. | ~210 tools, ready to call Bring your own MCP servers MCP n pill in the chat input → Add Server and paste any MCP endpoint HTTP, SSE, or stdio . Your tools join RuFlo's native ones in the same parallel-execution flow. Run a local MCP server on localhost:3000 and it just works. Tools run in parallel Step 1 — 2 tools completed badge so you can see exactly what ran. Memory that sticks "remember my favorite color is indigo" and ask weeks later — RuFlo recalls it. Backed by AgentDB + HNSW vector search measured ~1.9x–4.7x faster than brute force above the crossover, recall@10 ~0.99 . Built-in capabilities tour Self-hostable ruflo/src/ruvocal/Dockerfile with embedded Mongo. Deploy to your own Cloud Run / Fly / Kubernetes / docker-compose. The hosted flo.ruv.io https://flo.ruv.io/ demo is one option; running your own is fully supported. Zero install to try Try the hosted demo: https://flo.ruv.io/ https://flo.ruv.io/ — no account, no API key. Run your own: the source lives in ruflo/src/ruvocal/ /ruvnet/ruflo/blob/main/ruflo/src/ruvocal with a multi-stage Dockerfile INCLUDE DB=true builds in MongoDB and a cloudbuild.yaml for Google Cloud Run. See ADR-033 /ruvnet/ruflo/blob/main/ruflo/docs/adr/ADR-033-RUVOCAL-WASM-MCP-INTEGRATION.md for the architecture and issue 1689 https://github.com/ruvnet/ruflo/issues/1689 for the roadmap. Goal Planner UI — autonomous agents at goal.ruv.io https://goal.ruv.io/ Turn high-level goals into executable agent plans. goal.ruv.io is RuFlo's hosted Goal-Oriented Action Planning GOAP front-end — describe an outcome in plain English and watch RuFlo decompose it into preconditions, actions, and an A path through state space, then dispatch the work to live agents at /agents https://goal.ruv.io/agents . | What it is | Why it matters | | |---|---|---| | 🎯 | Plain-English goals | Type "ship the auth refactor with tests and a PR" — RuFlo extracts the success criteria, the constraints, and the implicit preconditions. No JSON, no DSL. | | 🧭 | GOAP A planner | Classic gaming-AI planning ported to software work: state-space search through actions with preconditions/effects to find the shortest viable path. Replans on the fly when state changes. | | 🤖 | Live agent dashboard | | Visual plan tree exactly why an agent picked a path — no opaque chain-of-thought. Adaptive replanning Shared memory + SONA Wired to MCP tools Zero install to try goal.ruv.io https://goal.ruv.io/ , describe a goal, watch it run. Source lives in — Vite + Supabase, self-hostable. /ruvnet/ruflo/blob/main/v3/goal ui v3/goal ui/ Try it: https://goal.ruv.io/ https://goal.ruv.io/ for goals · https://goal.ruv.io/agents https://goal.ruv.io/agents for live agents. Run your own: clone the goal branch and cd v3/goal ui && npm install && npm run dev . php Your Agent -- Remove secrets -- Sign message -- Encrypted channel Emails, SSNs, Proves it came No one reads it keys stripped from you in transit | v Their Agent <-- Block attacks <-- Check identity <------+ Stops prompt Rejects forgeries injection Audit trail on both sides. Trust builds over time. Bad behavior = instant downgrade. Slack gave teams channels. Federation gives agents the same thing — shared workspaces across trust boundaries , where agents on different machines, orgs, or cloud regions can discover each other, prove who they are, and collaborate on tasks. The difference: some channels are trusted, some aren't. @claude-flow/plugin-agent-federation https://github.com/ruvnet/ruflo/issues/1669 handles that automatically. Your agents join a federation, get verified via mTLS + ed25519, and start exchanging work — with PII stripped before anything leaves your node and every message auditable. Untrusted agents can still participate at lower privilege: they see discovery info, not your memory. As they prove reliable, trust upgrades. If they misbehave, they get downgraded instantly — no human in the loop required. You don't configure handshakes or manage certificates. You federation init , federation join , and your agents start talking. The protocol handles identity, the PII pipeline handles data safety, and the audit trail handles compliance. 📘 Full user guide: — setup, MCP tools, trust levels, circuit breaker, and the opt-in WireGuard mesh layer that ties packet-layer reachability to federation trust. ADR-111 deep-dive at docs/federation/ . docs/federation/phase7-mesh-bringup.md Federation capabilities | Capability | How it works | | |---|---|---| | 🔒 | Zero-trust federation | Remote agents start untrusted. Identity proven via mTLS + ed25519 challenge-response. No API keys, no shared secrets. | | 🛡️ | PII-gated data flow | 14-type detection pipeline scans every outbound message. Per-trust-level policies: BLOCK, REDACT, HASH, or PASS. Adaptive calibration reduces false positives. | | 📊 | Behavioral trust scoring | Formula 0.4×success + 0.2×uptime + 0.2×threat + 0.2×integrity continuously evaluates peers. Upgrades require history; downgrades are instant. | | 📋 | Compliance built-in | HIPAA, SOC2, GDPR audit trails as compliance modes. Every federation event produces a structured record searchable via HNSW. | | 🤝 | 9 MCP tools + 10 CLI commands | Full lifecycle: federation init , federation send , federation trust , federation audit , and more. | Example: two teams sharing fraud signals without sharing customer data Team A: initialize federation and generate keypair npx claude-flow@latest federation init Team A: join Team B's federation endpoint npx claude-flow@latest federation join wss://team-b.example.com:8443 Team A: send a task — PII is stripped automatically before it leaves npx claude-flow@latest federation send --to team-b --type task-request \ --message "Analyze transaction patterns for account anomalies" Team A: check peer trust levels and session health npx claude-flow@latest federation status See issue 1669 https://github.com/ruvnet/ruflo/issues/1669 for the complete architecture, trust model, and implementation roadmap. Claude Code plugin /plugin install ruflo-federation@ruflo Or via CLI npx claude-flow@latest plugins install @claude-flow/plugin-agent-federation Claude Code: With vs Without Ruflo | Capability | Claude Code Alone | + Ruflo | |---|---|---| | Agent Collaboration | Isolated, no shared context | Swarms with shared memory and consensus | | Coordination | Manual orchestration | Queen-led hierarchy Raft, Byzantine, Gossip | | Memory | Session-only | HNSW vector memory with sub-ms retrieval | | Learning | Static behavior | SONA self-learning with pattern matching | | Task Routing | You decide | Intelligent routing 89% accuracy | | Background Workers | None | 12 auto-triggered workers | | LLM Providers | Anthropic only | 5 providers with failover | | Security | Standard | CVE-hardened with AIDefence | Architecture overview php User -- Claude Code / CLI | v Orchestration Layer MCP Server, Router, 27 Hooks | v Swarm Coordination Queen, Topology, Consensus | v 100+ Specialized Agents coder, tester, reviewer, architect, security... | v Memory & Learning AgentDB, HNSW, SONA, ReasoningBank | v LLM Providers Claude, GPT, Gemini, Cohere, Ollama Four docs for four audiences: | Doc | When to read it | |---|---| | See what currently works — capability counts, test baselines, recent fixes, what's next. The is-it-ready doc. | | Daily reference — every command, every config flag, every plugin. The how-do-I doc. | | How to grade your agent setup, scan tool configs for security, detect changes between runs, and eject a project into a standalone agent toolkit. The audit-my-setup doc. | | v3.8.0 SOTA matrix vs LangGraph / AutoGen / CrewAI on darwin-arm64 + linux-x64. ruflo wins cold start, single turn, RSS by 1.3×–1953×. The is-it-fast doc. | | Cryptographically prove your installed bytes match the signed witness — ruflo verify . The trust-but-verify doc. | | Before-merge gates, dual-mode handoff, memory namespace sharing, and witness manifest entry per merge. The safer-team-workflows doc. | Benchmark internals for reproduction : sota-workload-spec.md https://github.com/ruvnet/ruflo/blob/perf/sota-comparator-benchmarks/docs/benchmarks/sota-workload-spec.md · · https://github.com/ruvnet/ruflo/blob/perf/sota-comparator-benchmarks/docs/benchmarks/SOTA-PROGRESS.md SOTA-PROGRESS.md raw matrix JSON: darwin https://github.com/ruvnet/ruflo/blob/perf/sota-comparator-benchmarks/docs/benchmarks/sota-matrix.json · linux https://github.com/ruvnet/ruflo/blob/perf/sota-comparator-benchmarks/docs/benchmarks/sota-matrix-linux.json User Guide section index: | Section | Topics | |---|---| | Core Features /ruvnet/ruflo/blob/main/docs/USERGUIDE.md -core-features Intelligence & Learning /ruvnet/ruflo/blob/main/docs/USERGUIDE.md -intelligence--learning Swarm & Coordination /ruvnet/ruflo/blob/main/docs/USERGUIDE.md -swarm--coordination Security /ruvnet/ruflo/blob/main/docs/USERGUIDE.md %EF%B8%8F-security Ecosystem /ruvnet/ruflo/blob/main/docs/USERGUIDE.md -ecosystem--integrations Configuration /ruvnet/ruflo/blob/main/docs/USERGUIDE.md %EF%B8%8F-configuration--reference Plugin Marketplace https://ruvnet.github.io/ruflo | Resource | Link | |---|---| | Documentation | | GitHub Issues https://github.com/ruvnet/claude-flow/issues ruv.io https://ruv.io Agentics Foundation Discord https://discord.com/invite/dfxmpwkG2D Cognitum.one https://cognitum.one MIT - RuvNet https://github.com/ruvnet