π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
revert: restore original README.md
ruvnet456b8e2a14ac
diff --git a/README.md b/README.mdindex 4cbb4f2ee4..4f2aaf2560 100644--- a/README.md+++ b/README.md@@ -1,161 +1,416 @@+<div align="center">++[](https://cognitum.one/agentic-engineering)++[](https://flo.ruv.io/)+[](https://goal.ruv.io/)+[](https://goal.ruv.io/agents)++[](https://www.npmjs.com/package/ruflo)+[](https://github.com/ruvnet/ruflo/blob/main/data/clone-data.proof.json)+[](https://github.com/ruvnet/ruflo/blob/main/data/clone-data.ledger.json)++[](https://github.com/ruvnet/claude-flow)+[](https://opensource.org/licenses/MIT)+[](https://github.com/ruvnet/claude-flow)+[](https://www.npmjs.com/package/@claude-flow/codex)+[](https://github.com/ruvnet/ruvector)++[](https://cognitum.one/appliance)++[](https://github.com/ruvnet/ruflo/issues/1967)+# Ruflo-**A multi-agent harness for Claude Code and Codex.**+**Multi-agent AI harness for Claude Code and Codex**-Ruflo is a CLI and MCP server that turns Claude Code into a coordinated team of AI agents instead of one assistant working in a loop. It adds three things on top of a normal Claude Code install:+</div>-1. **Swarms of agents** that can split up work and message each other.-2. **Persistent memory** so the model remembers what worked across sessions, not just within one chat.-3. **Hooks** that automatically route tasks to cheaper or more capable models based on what they actually are.+Orchestrate 100+ specialized AI agents across machines, teams, and trust boundaries. Ruflo adds coordinated swarms, self-learning memory, federated comms, and enterprise security to Claude Code β so agents don't just run, they collaborate.-You still write code in Claude Code the way you already do. Ruflo runs in the background.+### Why Ruflo?----+> Claude Flow is now Ruflo β named by [`rUv`](https://ruv.io), 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 [`Cognitum.One`](https://cognitum.one/?RuFlo) agentic architecture, running a supercharged Rust based AI engine, embeddings, memory, and plugin system.-## What problem it solves-A single Claude session forgets everything when it ends, can only do one thing at a time, and uses the same model for "rename a variable" as it does for "design the auth system." Ruflo fixes the three:+### What Ruflo Does-- **Forgetting** β every successful pattern is stored in a vector database. Next time you ask something similar, the agent has the prior solution as context.-- **One thing at a time** β instead of one agent looping over a feature, several named agents (architect, coder, tester, reviewer) work in parallel and message each other directly.-- **One model for everything** β a routing layer picks the cheapest tier that can actually do the task. Trivial code transforms run as deterministic codemods at $0; medium tasks go to Haiku (~$0.0002); hard reasoning goes to Sonnet or Opus.+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.++```+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.----## Install+-You need Node 20+, a Claude Code install, and an Anthropic API key (or another supported provider).+## Quick Start-```bash-# Option 1 β the wrapper (recommended). Sets everything up in the current directory.-npx ruflo init+There are **two different install paths** with very different surface areas. Pick based on what you need (#1744):-# Option 2 β the CLI directly.-npx @claude-flow/cli@latest init --wizard+| | **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 |-# Option 3 β Claude Code plugin only (no MCP server, slash commands only).+### Path A β Claude Code Plugins (lite, slash commands only)++```bash+# 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```-After `init`, restart Claude Code so it picks up the new MCP server and hooks.+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.-To check the install:+<details>+<summary><strong>π All 33 plugins</strong></summary>-```bash-npx ruflo doctor --fix-```+#### Core & Orchestration----+| Plugin | What it does |+|--------|-------------|+| [**ruflo-core**](plugins/ruflo-core/README.md) | Foundation β server, health checks, plugin discovery |+| [**ruflo-swarm**](plugins/ruflo-swarm/README.md) | Coordinate multiple agents as a team |+| [**ruflo-autopilot**](plugins/ruflo-autopilot/README.md) | Let agents run autonomously in a loop |+| [**ruflo-loop-workers**](plugins/ruflo-loop-workers/README.md) | Schedule background tasks on a timer |+| [**ruflo-workflows**](plugins/ruflo-workflows/README.md) | Reusable multi-step task templates |+| [**ruflo-federation**](plugins/ruflo-federation/README.md) | Agents on different machines collaborate securely |-## What `init` does+#### Memory & Knowledge-It writes a few things into your project and your Claude config:+| Plugin | What it does |+|--------|-------------|+| [**ruflo-agentdb**](plugins/ruflo-agentdb/README.md) | Fast vector database for agent memory |+| [**ruflo-rag-memory**](plugins/ruflo-rag-memory/README.md) | Smart retrieval β hybrid search, graph hops, diversity ranking |+| [**ruflo-rvf**](plugins/ruflo-rvf/README.md) | Save and restore agent memory across sessions |+| [**ruflo-ruvector**](plugins/ruflo-ruvector/README.md) | [`ruvector`](https://npmjs.com/package/ruvector) β GPU-accelerated search, Graph RAG, 103 tools |+| [**ruflo-knowledge-graph**](plugins/ruflo-knowledge-graph/README.md) | Build and traverse entity relationship maps |-| Path | What it is |-|------|------------|-| `.claude/settings.json` | Hooks wiring (pre-edit, post-edit, session-start, etc.) so Ruflo gets called by Claude Code |-| `.claude/helpers/` | Small scripts the hooks point at β pattern recording, routing decisions, statusline |-| `.claude-flow/` | Local state β memory database, learned patterns, session logs |-| `CLAUDE.md` | Project rules Claude Code reads on every turn. Edit this to teach Claude about your project |-| `data/memory/` | The vector-indexed memory store (created on first use) |+#### Intelligence & Learning-No files outside the project directory are touched. To undo, delete those paths.+| Plugin | What it does |+|--------|-------------|+| [**ruflo-intelligence**](plugins/ruflo-intelligence/README.md) | Agents learn from past successes and get smarter |+| [**ruflo-graph-intelligence**](plugins/ruflo-graph-intelligence/) | Sublinear graph reasoning β PageRank, delta updates, complexity-aware execution (ADR-123) |+| [**ruflo-daa**](plugins/ruflo-daa/README.md) | Dynamic agent behavior and cognitive patterns |+| [**ruflo-ruvllm**](plugins/ruflo-ruvllm/README.md) | Run local LLMs (Ollama, etc.) with smart routing |+| [**ruflo-goals**](plugins/ruflo-goals/README.md) | Break big goals into plans and track progress |----+#### Code Quality & Testing++| Plugin | What it does |+|--------|-------------|+| [**ruflo-testgen**](plugins/ruflo-testgen/README.md) | Find missing tests and generate them automatically |+| [**ruflo-browser**](plugins/ruflo-browser/README.md) | Automate browser testing with Playwright |+| [**ruflo-jujutsu**](plugins/ruflo-jujutsu/README.md) | Analyze git diffs, score risk, suggest reviewers |+| [**ruflo-docs**](plugins/ruflo-docs/README.md) | Generate and maintain documentation automatically |++#### Security & Compliance++| Plugin | What it does |+|--------|-------------|+| [**ruflo-security-audit**](plugins/ruflo-security-audit/README.md) | Scan for vulnerabilities and CVEs |+| [**ruflo-aidefence**](plugins/ruflo-aidefence/README.md) | Block prompt injection, detect PII, safety scanning |-## Three things you can actually use day-to-day+#### Architecture & Methodology-### 1. Spawn a team instead of a single agent+| Plugin | What it does |+|--------|-------------|+| [**ruflo-adr**](plugins/ruflo-adr/README.md) | Track architecture decisions with a living record |+| [**ruflo-ddd**](plugins/ruflo-ddd/README.md) | Scaffold domain-driven design β contexts, aggregates, events |+| [**ruflo-sparc**](plugins/ruflo-sparc/README.md) | Guided 5-phase development methodology with quality gates |-In Claude Code, instead of asking one agent to do everything, ask it to spawn a team:+#### DevOps & Observability-> "Use a swarm to add OAuth login. Architect β coder β tester β reviewer."+| Plugin | What it does |+|--------|-------------|+| [**ruflo-migrations**](plugins/ruflo-migrations/README.md) | Manage database schema changes safely |+| [**ruflo-observability**](plugins/ruflo-observability/README.md) | Structured logs, traces, and metrics in one place |+| [**ruflo-cost-tracker**](plugins/ruflo-cost-tracker/README.md) | Track token usage, set budgets, get cost alerts |-Claude will use the Task tool to spawn named background agents that message each other. You'll see progress for each one. You don't have to manage them; they coordinate via `SendMessage`.+#### Extensibility-### 2. Search past work+| Plugin | What it does |+|--------|-------------|+| [**ruflo-agent**](plugins/ruflo-agent/README.md) | Run agents β local WASM sandbox (rvagent) + Anthropic Claude Managed Agents (cloud) |+| [**ruflo-plugin-creator**](plugins/ruflo-plugin-creator/README.md) | Scaffold, validate, and publish your own plugins |-The memory store is semantic β search by meaning, not by keyword:+#### Domain-Specific++| Plugin | What it does |+|--------|-------------|+| [**ruflo-iot-cognitum**](plugins/ruflo-iot-cognitum/README.md) | IoT device management β trust scoring, anomaly detection, fleets |+| [**ruflo-neural-trader**](plugins/ruflo-neural-trader/README.md) | [`neural-trader`](https://npmjs.com/package/neural-trader) β AI trading with 4 agents, backtesting, 112+ tools |+| [**ruflo-market-data**](plugins/ruflo-market-data/README.md) | Ingest market data, vectorize OHLCV, detect patterns |++</details>++### CLI Install++**macOS / Linux / WSL / Git-Bash:**```bash-npx ruflo memory search --query "authentication patterns"-npx ruflo memory search --query "the bug where login redirected to /undefined"+# One-line install (POSIX shells only β see Windows note below)+curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash```-Use this when you suspect you've solved something similar before and don't want to re-derive it.--### 3. Check what the model would cost before spawning+**All platforms (including native Windows PowerShell / cmd):**```bash-npx ruflo hooks route --task "rename all snake_case variables to camelCase in src/api/"+# 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```-The router will tell you whether this is a $0 codemod (it is), a Haiku job, or needs Sonnet/Opus.+> π‘ **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.++### MCP Server++```bash+# Add Ruflo as an MCP server in Claude Code (canonical form, matches USERGUIDE.md)+claude mcp add ruflo -- npx ruflo@latest mcp start+```----## Core concepts in one sentence each+## What You Get++| 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 [audit](docs/reviews/intelligence-system-audit-2026-05-29.md) + [`scripts/benchmark-intelligence.mjs`](scripts/benchmark-intelligence.mjs) |+| β‘ **Background Workers** | 12 auto-triggered workers (audit, optimize, testgaps, etc.) |+| π§© **Plugin Marketplace** | 32 native Claude Code plugins + 21 npm plugins |+| π **Multi-Provider** | Claude, GPT, Gemini, Cohere, Ollama with smart routing |+| π‘οΈ **Security** | AIDefence, input validation, CVE remediation, path traversal prevention |+| π **Agent Federation** | Cross-installation agent collaboration with zero-trust security |+| π¬ **[Web UI Beta](https://flo.ruv.io/)** | Multi-model chat at flo.ruv.io with parallel MCP tool calling and an in-browser WASM tool gallery |+| π― **[RuFlo Research](https://goal.ruv.io/)** | GOAP A\* planner at goal.ruv.io β plain-English goals β executable agent plans, with a live agent dashboard at [/agents](https://goal.ruv.io/agents) |++<p align="center">+ <a href="https://flo.ruv.io/">+ <img src="v3/docs/assets/ruVocal.png" alt="RuFlo Web UI executing parallel MCP tool calls at flo.ruv.io β ruflo__memory_store and ruflo__memory_search firing in a single model turn with the 'Step 1 β 2 tools completed' parallel-execution indicator, thinking process panel visible, Qwen 3.6 Max as the active model. Multi-agent AI chat with Model Context Protocol (MCP) tool calling, persistent vector memory via AgentDB + HNSW, swarm coordination, and 6 frontier models including Claude Sonnet 4.6, Gemini 2.5 Pro, and OpenAI through OpenRouter." width="100%" />+ </a>+</p>++### 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 [ruvLLM](https://github.com/ruvnet/RuVector/tree/main/examples/ruvLLM) (lives in `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** | 5 server groups (Core, Intelligence, Agents, Memory, DevTools) plus an 18-tool gallery that runs entirely in your browser β works offline. |+| π | **Bring your own MCP servers** | Click the **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** | One model response can fire 4β6+ tools at the same time. The UI shows them as cards with a *Step 1 β 2 tools completed* badge so you can see exactly what ran. |+| πΎ | **Memory that sticks** | Say *"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** | Click the question-mark icon in the sidebar β a "RuFlo Capabilities" modal opens with the full tool list, model strengths, architecture, and keyboard shortcuts. |+| π | **Self-hostable** | Web UI is shipped as Docker (`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** | Open the hosted URL, pick a model, type a question. That's the whole onboarding. |++**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/`](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](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.++<p align="center">+ <a href="https://goal.ruv.io/agents">+ <img src="v3/docs/assets/goal.png" alt="goal.ruv.io/agents β RuFlo Goal-Oriented Action Planning (GOAP) UI for autonomous AI agents. Visual goal decomposition, A* search through state spaces, multi-agent task assignment, and live agent telemetry." width="100%" />+ </a>+</p>++### 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** | [goal.ruv.io/agents](https://goal.ruv.io/agents) shows every spawned agent β role, current step, memory namespace, token budget, status. Click in to inspect trajectories, kill runaway workers, or reassign. |+| π³ | **Visual plan tree** | Goals render as collapsible action trees with progress, blocked branches, and rollbacks highlighted. See *exactly* why an agent picked a path β no opaque chain-of-thought. |+| β»οΈ | **Adaptive replanning** | When an action fails or new info arrives, the planner re-runs A\* from the current state instead of restarting. Failures become learning, not loops. |+| π§ | **Shared memory + SONA** | Plans, trajectories, and outcomes flow into AgentDB. Future plans retrieve past solutions via HNSW β the planner gets smarter with every run. |+| π | **Wired to MCP tools** | Every action node maps to a tool call (RuFlo's ~210 MCP tools, your custom servers, or shell). The planner schedules them in parallel where the dependency graph allows. |+| π | **Zero install to try** | Open [goal.ruv.io](https://goal.ruv.io/), describe a goal, watch it run. Source lives in [`v3/goal_ui/`](v3/goal_ui/) β Vite + Supabase, self-hostable. |++**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`.++### Agent Federation β Slack for Agents-| Concept | What it is |-|---------|------------|-| **Agent** | A specialized Claude session with a role (e.g. `coder`, `tester`, `security-architect`) and a system prompt tuned for that role |-| **Swarm** | A group of agents working on the same task with a topology (hierarchical, mesh, hybrid) that controls who can talk to whom |-| **Hooks** | Shell commands Claude Code runs on lifecycle events (before/after edits, before/after commands, on session start). Ruflo uses them to record outcomes and route tasks |-| **Memory** | A vector database (HNSW-indexed) that stores successful patterns and lets future runs retrieve them by semantic similarity |-| **Routing** | A three-tier decision (codemod β Haiku β Sonnet/Opus) that picks the cheapest model that can still do the task |-| **MCP server** | The interface Claude Code uses to call Ruflo's tools (memory, swarm, hooks). Ruflo registers it during `init` |-| **Plugin** | An optional add-on (browser automation, GitHub workflows, neural trading, etc.) β install only what you need |+```+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.-## Common questions+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.-**Do I have to learn all 314 MCP tools and 26 CLI commands?**-No. After `init`, just use Claude Code normally. The hooks and routing run in the background.+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.-**Will it slow Claude down?**-Hooks add a few hundred milliseconds per tool call for the recording path. The routing layer typically saves more time than it costs because trivial tasks skip the LLM entirely.+> **π Full user guide:** [`docs/federation/`](./docs/federation/) β 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/phase7-mesh-bringup.md`](./docs/federation/phase7-mesh-bringup.md).-**Does it work with Codex?**-Yes. `@claude-flow/codex` runs Codex workers in parallel with Claude workers, sharing the same memory namespace. See `docs/dual-mode.md` if you want both.+<details>+<summary><strong>Federation capabilities</strong></summary>-**Does it phone home?**-No. Memory, hooks, and routing run locally. The only network calls are to the LLM provider you configured (Anthropic, OpenAI, etc.). The optional plugin registry uses IPFS via Pinata.+| | 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. |-**Where's my data?**-`.claude-flow/data/memory/` in the project root. SQLite + vector index. Delete the folder to wipe it.+</details>-**How do I uninstall?**-Delete `.claude/`, `.claude-flow/`, `CLAUDE.md`, and (if you used the wrapper) `npm uninstall -g ruflo`.+<details>+<summary><strong>Example: two teams sharing fraud signals without sharing customer data</strong></summary>----+```bash+# 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+```++</details>-## When you should NOT use Ruflo+See [issue #1669](https://github.com/ruvnet/ruflo/issues/1669) for the complete architecture, trust model, and implementation roadmap.-- You're working in one file for ten minutes. Just use Claude Code directly.-- You don't want anything in your project directory. Use the Claude Code plugins instead (`/plugin install ruflo-core@ruflo`).-- You're on a machine where you can't run a background daemon (the daemon is optional, but several features need it).+```bash+# Claude Code plugin+/plugin install ruflo-federation@ruflo++# Or via CLI+npx claude-flow@latest plugins install @claude-flow/plugin-agent-federation+```++<details>+<summary><strong>Claude Code: With vs Without Ruflo</strong></summary>++| 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 |++</details>++<details>+<summary><strong>Architecture overview</strong></summary>++```+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)+```++</details>----## Help+## Documentation++Four docs for four audiences:++| Doc | When to read it |+|-----|-----------------|+| **[Status](docs/STATUS.md)** | See what currently works β capability counts, test baselines, recent fixes, what's next. The *is-it-ready* doc. |+| **[User Guide](docs/USERGUIDE.md)** | Daily reference β every command, every config flag, every plugin. The *how-do-I* doc. |+| **[Benchmarks](https://gist.github.com/ruvnet/298f8c668c8859b369f91734a0e9cbbe)** | 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. |+| **[Verification](verification.md)** | Cryptographically prove your installed bytes match the signed witness β `ruflo verify`. The *trust-but-verify* doc. |+| **[Team Gateway Checklist](docs/TEAM-GATEWAY-CHECKLIST.md)** | 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) Β· [`SOTA-PROGRESS.md`](https://github.com/ruvnet/ruflo/blob/perf/sota-comparator-benchmarks/docs/benchmarks/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)-| | |-|---|---|-| Docs | https://github.com/ruvnet/ruflo/tree/main/docs |-| Issues | https://github.com/ruvnet/ruflo/issues |-| Releases | https://github.com/ruvnet/ruflo/releases |-| npm β `ruflo` | https://www.npmjs.com/package/ruflo |-| npm β `@claude-flow/cli` | https://www.npmjs.com/package/@claude-flow/cli |-| Cognitum β the agentic engine | https://cognitum.one/ |+User Guide section index:-To file a bug, run `npx ruflo doctor` and paste the output into the issue. That captures the version, Node version, MCP server state, and which hooks are wired β most of what someone debugging will ask for.+| Section | Topics |+|---------|--------|+| [Quick Start](docs/USERGUIDE.md#quick-start) | Installation, prerequisites, install profiles |+| [Core Features](docs/USERGUIDE.md#-core-features) | MCP tools, agents, memory, neural learning |+| [Intelligence & Learning](docs/USERGUIDE.md#-intelligence--learning) | Hooks, workers, SONA, model routing |+| [Swarm & Coordination](docs/USERGUIDE.md#-swarm--coordination) | Topologies, consensus, hive mind |+| [Security](docs/USERGUIDE.md#%EF%B8%8F-security) | AIDefence, CVE remediation, validation |+| [Ecosystem](docs/USERGUIDE.md#-ecosystem--integrations) | RuVector, agentic-flow, Flow Nexus |+| [Configuration](docs/USERGUIDE.md#%EF%B8%8F-configuration--reference) | Environment variables, config schema |+| [Plugin Marketplace](https://ruvnet.github.io/ruflo) | Browse and install plugins |----## License+## Support++| Resource | Link |+|----------|------|+| Documentation | [User Guide](docs/USERGUIDE.md) |+| Issues & Bugs | [GitHub Issues](https://github.com/ruvnet/claude-flow/issues) |+| Enterprise | [ruv.io](https://ruv.io) |+| Community | [Agentics Foundation Discord](https://discord.com/invite/dfxmpwkG2D) |+| Powered by | [Cognitum.one](https://cognitum.one) |-MIT. See [LICENSE](LICENSE).+## License-> Ruflo is the rename of Claude Flow. The name is `rUv` ("Ru") + "flow" ("flo"). It's powered by [Cognitum.One](https://cognitum.one/) β a Rust-based engine for embeddings, memory, and the plugin system.+MIT - [RuvNet](https://github.com/ruvnet)