Ruflo for Beginners: a Multi-Agent Collaboration Engine That Self-Improves

Project overview

Ruflo is a multi-agent orchestration layer designed for Claude Code. In one sentence, it does this: it turns Claude Code from a “Q&A helper” into an AI team that can collaborate, remember, and self-improve.

Ruflo was originally called Claude Flow, developed by RuvNet (the founder has a Rust background, and the name combines the “Ruv” + “flow” imagery). Under the hood, a WASM kernel written in Rust powers the strategy engine, vector embeddings, and a proof system—built to deliver high performance. The newest stable release, [email protected], is already a complete enterprise-ready product:

• 300+ MCP tools injected directly into Claude Code
• 60+ professional Agent roles (coder, tester, architect, security-architect……)
• Self-learning memory: AgentDB + an HNSW vector index; search is 150× to 12,500× faster than brute force
• Cross-machine federated collaboration: Agent Federation, zero-trust secure communication based on mTLS + ed25519
• Self-improvement capability: the SONA neural learning module extracts patterns from historical trajectories and continuously optimizes
• 32 plugins covering security, cost tracking, browser automation, GitHub integration, and more

Its design philosophy is particularly interesting—after installing, you don’t need to learn 300 MCP tools. The Hooks routing layer automatically dispatches tasks to the right Agent. You keep writing code, and Ruflo coordinates everything in the background.

Difficulty / Time / What you’ll gain

• Difficulty: ★★☆☆☆ (install and run in about 5 minutes)
• Time: ~20 minutes
• What you’ll gain: swarm topology and lifecycle management, understand how HNSW vector memory works, and learn how Agents communicate with each other via SendMessage

Target audience

• Developers with 1–5 years of experience
• Want to turn AI from a “chat tool” into a “working team”
• Individual developers or small teams that already use (or plan to use) Claude Code for development

Core dependencies and environment

Full project directory tree

ruflo/
├── bin/
│   ├── cli.js              # CLI entry (ruflo command)
│   └── mcp-server.js       # MCP server
│
├── v3/@claude-flow/        # Core module package
│   ├── cli/                # 26 top-level commands (140+ subcommands)
│   ├── memory/             # AgentDB + HNSW vector search
│   ├── swarm/              # Unified coordinator (15-agent hierarchical mesh)
│   ├── security/           # CVE fixes, input validation, path safety
│   ├── neural/             # SONA self-learning module
│   ├── hooks/              # 17 Hooks + 12 background workers
│   ├── guidance/           # Governance control plane (compile/enforce/prove/evolve)
│   └── shared/             # Types, events, and core interfaces
│
├── plugins/                # 32 official plugins
│   ├── ruflo-core/         # Core (server, health checks, plugin discovery)
│   ├── ruflo-swarm/        # Multi-Agent team coordination
│   ├── ruflo-federation/   # Cross-machine secure collaboration
│   ├── ruflo-agentdb/      # Vector database memory
│   ├── ruflo-intelligence/ # Self-learning neural patterns
│   └── ...                 # The remaining 27 plugins
│
├── .claude/                # Claude Code configuration (MCP server, settings.json)
├── .agents/                # Agent skill definitions ($skill-name syntax)
└── mcp/                    # MCP tool definitions (agent-tools.ts, memory-tools.ts, etc.)

Hands-on walkthrough

Step 1: One-command installation

One command to initialize it, with a guided setup wizard:

npx ruflo@latest init --wizard

This command will do the following in order:

1. Generate CLAUDE.md in the current directory and write the Hooks routing rules
2. Register the MCP server in the Claude Code configuration
3. Write the default configuration and a memory seed file under .claude-flow/

If it’s your first installation, choose the “full” install option so that all optional modules are included.

---

Step 2: Register the MCP service

If the previous step didn’t auto-register the MCP, add it manually:

claude mcp add ruflo -- npx -y @claude-flow/cli@latest mcp start

Verify registration:

claude mcp list
# Expected output similar to:
# Name    Command                          Args  Status
# ruflo   npx -y @claude-flow/cli@latest  mcp  enabled

---

Step 3: Initialize your first Swarm (hierarchical + 5 Agents)

npx ruflo swarm init --topology hierarchical --max-agents 8
npx ruflo agent spawn --type architect --name arch-1
npx ruflo agent spawn --type coder --name coder-1
npx ruflo agent spawn --type coder --name coder-2
npx ruflo agent spawn --type tester --name tester-1
npx ruflo agent spawn --type reviewer --name reviewer-1

---

Step 4: Let Agents communicate via SendMessage

This is Ruflo’s core design—named Agents communicate in real time via SendMessage, without polling or a shared memory pool:

// Use it in Claude Code’s Task tool:
Task({
  prompt: "Design a REST API方案. After you finish, SendMessage it to 'coder-1' with the proposal.",
  subagent_type: "system-architect",
  name: "arch-1",
  run_in_background: true
})

Task({
  prompt: "Wait for the design from arch-1. After implementing, SendMessage to 'tester-1' with the code path.",
  subagent_type: "coder",
  name: "coder-1",
  run_in_background: true
})

Task({
  prompt: "Wait for the code from coder-1. Write integration tests. When done, SendMessage the result to 'reviewer-1'.",
  subagent_type: "tester",
  name: "tester-1",
  run_in_background: true
})

// Start the pipeline by sending a message to the first Agent
SendMessage({
  to: "arch-1",
  summary: "Start API design",
  message: "Design a set of CRUD REST APIs for user management, including create/read/update/delete. After the design is ready, send it to coder-1."
})

Pipeline flow: arch-1 → coder-1 → tester-1 → reviewer-1. Each Agent knows who to send the next step to.

---

Step 5: Store your first memory (AgentDB + HNSW)

npx ruflo memory store \
  --key "pattern-auth-service" \
  --value "JWT authentication: Bearer Token, use express-jwt as middleware, store refresh tokens in Redis, expire in 6 hours" \
  --namespace patterns

The stored content automatically generates vector embeddings, and it’s saved into AgentDB for later semantic search.

---

Step 6: Validate memory with semantic search

npx ruflo memory search --query "authentication patterns" --namespace patterns

The output will show matching entries and similarity scores (0–1; higher means more relevant). A score > 0.7 indicates a strong match—you can use it directly.

---

Step 7: Start the background Daemon and run health diagnostics

# Start the background watchdog (12 automatic workers will begin running)
npx ruflo daemon start

# One-click diagnostics (checks Node version, API Key, MCP connections, disk space)
npx ruflo doctor --fix

doctor --fix will automatically repair issues it can fix (e.g., missing dependencies) and output a complete health report in your terminal.

---

Step 8: Install plugins (as needed)

Plugins are easy to install—pick the functionality you need:

# Add the plugin marketplace
/plugin marketplace add ruvnet/ruflo

# Install the federation collaboration plugin (cross-machine Agent communication)
/plugin install ruflo-federation@ruflo

# Install the self-learning plugin (SONA neural patterns)
/plugin install ruflo-intelligence@ruflo

# Install the security audit plugin
/plugin install ruflo-security-audit@ruflo

# Install the cost tracking plugin
/plugin install ruflo-cost-tracker@ruflo

Or use the CLI:

npx ruflo plugins install ruflo-federation
npx ruflo plugins list  # View all available plugins

---

Step 9: Advanced—invoke self-improvement capability (SONA)

# Let SONA extract patterns from recent successful cases and train
npx ruflo hooks post-task --task-id "abc-123" --success true --train-neural true

# View the patterns currently being learned
npx ruflo neural patterns

# Have the routing layer use intelligent routing (89% accuracy)
npx ruflo hooks route --task "Write an API middleware"

SONA runs a 4-stage pipeline in the background: RETRIEVE (HNSW) → JUDGE (success/failure evaluation) → DISTILL (LoRA distillation) → CONSOLIDATE (EWC++ to prevent catastrophic forgetting).

---

Troubleshooting common issues

1. MCP connection failed: ruflo shows disabled in claude mcp list

Usually it’s a Node version issue or the port is already in use:

# Check Node version
node -v  # Must be ≥20.0.0

# Manually restart the MCP service
claude mcp remove ruflo
claude mcp add ruflo -- npx -y @claude-flow/cli@latest mcp start

# Confirm port usage
lsof -i :3000  # macOS
netstat -tlnp | grep 3000  # Linux

---

2. API Key is not configured; error: ANTHROPIC_API_KEY is not set

Ruflo needs at least one provider’s API key for an LLM:

# Temporary set (valid for the current session)
export ANTHROPIC_API_KEY=sk-ant-xxxx

# Persist it in ~/.bashrc or ~/.zshrc
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxx' >> ~/.zshrc

# Or use a config file (init --wizard will guide you to write .env)
# Supports multiple providers: Claude / GPT / Gemini / Ollama
npx ruflo providers add anthropic --key sk-ant-xxxx
npx ruflo providers test anthropic  # Test the connection

---

3. Node version doesn’t meet requirements: ruflo: requires Node.js >=20.0.0

# Method one: upgrade using nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 20
nvm use 20

# Method two: use nvm-windows on Windows
# Download the installer: https://github.com/coreybutler/nvm-windows/releases
nvm install 20
nvm use 20

# Verify
node -v  # Should show v20.x.x

---

4. memory search returns no results

It may be due to a wrong namespace, or the memory hasn’t been stored yet:

# List all namespaces
npx ruflo memory list --namespace

# List all keys in patterns
npx ruflo memory list --namespace patterns

# Retrieve a known key directly
npx ruflo memory retrieve --key "pattern-auth-service"

# If the library is empty, try storing one first
npx ruflo memory store --key "test-entry" --value "hello world" --namespace patterns
npx ruflo memory search --query "test" --namespace patterns

---

5. After starting the swarm, all Agents are idle

This means no tasks have been dispatched yet. Check the following:

# View all Agent statuses
npx ruflo agent list

# Check whether the swarm has been initialized
npx ruflo swarm status

# If you started it with Claude Code’s Task tool, confirm you sent the start message:
# SendMessage({ to: "arch-1", message: "Start working" })
# Without SendMessage, the first Agent won’t start automatically

---

6. ruflo doctor reports MongoDB not running

When starting via Docker Compose (ruflo/src/ruvocal/), MongoDB is required:

# Option one: start full dependencies with Docker
cd ruflo/src/ruvocal
docker compose up -d

# Option two: use Ruflo’s built-in standalone mode (no MongoDB needed)
npx ruflo start --mode standalone
# standalone uses sql.js (WASM) instead of MongoDB and works fully offline

---

Further reading / Advanced directions

1. Agent Federation—zero-trust collaboration across machines

One of the coolest features. Let Agents on different machines collaborate; PII is automatically filtered before being sent:

npx ruflo federation init
npx ruflo federation join wss://other-team.example.com:8443
npx ruflo federation send --to team-b --type task-request --message "Analyze transaction patterns"

Architecture details: each outbound message undergoes 14 types of PII detection → four-level policy (BLOCK / REDACT / HASH / PASS) → identity verification with mTLS + ed25519 signatures. Malicious behavior triggers trust downgrade automatically—no manual intervention required.

2. How RuVector HNSW vector search works

It’s not simple keyword matching. Text is encoded into 384-dimensional vectors, then the nearest neighbors are found in vector space using the HNSW (Hierarchical Navigable Small World) algorithm. Each memory store automatically generates embeddings, and each memory search ranks results by cosine similarity.

3. Quick guide to the 32-plugin ecosystem

4. Online experience (no installation)

• Multi-model chat UI: https://flo.ruv.io/ — supports Qwen 3.6 Max / Claude Sonnet / Gemini 2.5 Pro, and calls MCP tools in parallel
• Goal planning UI: https://goal.ruv.io/ — turns your described task (“rebuild Auth and write tests”) into a GOAP A* path
• Live Agent dashboard: https://goal.ruv.io/agents — monitor each Agent’s status, memory namespaces, and token budget in real time

5. Official documentation index

6. Discord community

Having trouble, or want to share the Skills you built? RuvNet maintains an active community on the Agentics Foundation Discord:

https://discord.com/invite/dfxmpwkG2D

There are tons of user-made $skill-name skills you can use right away.