The complete guide to installing, configuring, and using RuFlo with Claude Code — from your first swarm to production-grade agent orchestration.

Most people use Claude Code as a single agent. One prompt, one task, one response. But what if you could run 100+ specialized agents — coders, testers, reviewers, architects — all working together in coordinated swarms? That's what the RuFlo stack does. This guide shows you how to set it up from scratch.

🧠 What Is the RuFlo Stack?

RuFlo is an open-source agent orchestration platform that transforms Claude Code into a multi-agent development powerhouse.

Instead of one AI doing everything, RuFlo deploys specialized agent teams — each optimized for a specific role — that communicate, share memory, and divide work automatically.

Think of it like this:

  • Claude Code alone = one smart developer
  • Claude Code + RuFlo = an entire engineering team with a coordinator, architects, coders, testers, and reviewers — all running simultaneously

Key capabilities at a glance:

📋 Prerequisites

Before you start, make sure you have:

🚀 Step 1: Install RuFlo

Open your terminal and run the one-line installer:

npx ruflo@latest init --wizard

This launches the interactive setup wizard that walks you through configuration.

For a full setup (global install + MCP server + diagnostics):

npx ruflo@latest init --full

Which install should you pick? If you're just trying RuFlo for the first time, use --wizard. It asks you questions and sets everything up based on your answers. Use --full if you already know you want the complete toolkit.

Install speed reference:

🔧 Step 2: Configure MCP Integration

RuFlo plugs directly into Claude Code via MCP (Model Context Protocol). This gives you access to 310+ tools right inside your Claude Code session.

After install, set up MCP:

npx ruflo@latest init --setup-mcp

Once configured, you can use RuFlo commands directly in Claude Code — no switching between tools.

Verify it's working: Run npx ruflo@latest hooks intelligence --status in your terminal. You should see a status report showing all active components.

🐝 Step 3: Run Your First Agent Swarm

This is where it gets powerful. Instead of prompting Claude Code with one task, you're now deploying a coordinated team.

The Anti-Drift Configuration (Recommended)

For your first swarm, use the anti-drift defaults. This keeps agents focused and prevents them from going off-task:

swarm_init({
  topology: "hierarchical",  // Single coordinator enforces alignment
  maxAgents: 8,              // Smaller team = less drift
  strategy: "specialized"    // Clear roles reduce ambiguity
})

Choosing the Right Swarm for Your Task

🧠 Step 4: Set Up Self-Learning Memory

This is what makes RuFlo fundamentally different from vanilla Claude Code. The system remembers what works and gets smarter over time.

How the Learning Loop Works

  1. RETRIEVE — Fetches relevant patterns from memory
  2. JUDGE — Evaluates which patterns apply to the current task
  3. DISTILL — Extracts the useful insight
  4. CONSOLIDATE — Stores it for future use
  5. ROUTE — Routes similar future tasks to the best approach

The memory system includes:

  • HNSW vector search — sub-millisecond pattern retrieval
  • Knowledge graph — PageRank identifies the most influential insights
  • Agent scoping — per-agent memory isolation with cross-agent knowledge transfer

Why this matters: After a few sessions, RuFlo stops making the same mistakes. It learns your codebase patterns, your preferences, and the approaches that work best for your specific project. Claude Code alone resets every session.

💰 Step 5: Optimize for Cost (The Token Savings Framework)

RuFlo's smart routing can extend your Claude Code subscription by up to 250% by skipping expensive LLM calls when they're not needed.

How Smart Routing Works

Token Optimization Breakdown

🏗️ Step 6: Build a Real Project (Walkthrough)

Let's put it all together. Here's how to build a full-stack feature using the RuFlo stack:

Phase 1 — Plan

Tell your swarm to plan before building:

I want to build a user authentication system with OAuth support.
Before writing any code:
1. Outline the file structure
2. List the key components
3. Describe the data flow
4. Flag any decisions I need to make
5. Wait for my approval before coding

RuFlo's coordinator agent will distribute this across the architect and researcher agents, then present a unified plan.

Phase 2 — Build

Once you approve the plan, the swarm executes:

  • Architect defines the structure