Ruflo — Setup Guide¶
Source: ruvnet/ruflo (5.8K+ combined installs across skills) GitHub: ruvnet/ruflo — 65,762 ★ | MIT License | TypeScript Category: Agent Infrastructure / Orchestration Quality Tier: 🟢 Production (65K+ GitHub stars, v3.31.0 stable, active development)
Ruflo is the leading agent meta-harness — a cross-agent orchestration layer that works natively with Hermes, Claude Code, Codex, Cursor, Copilot, Gemini, Amp, and 12+ other coding agents. It ships as three npm packages and provides 314+ MCP tools for memory (HNSW vector search), multi-agent swarms (hierarchical/mesh with anti-drift), task lifecycle management, self-learning intelligence pipelines, hooks, routing, and 30+ optional plugins. With 65,762 GitHub stars and active development (822 open issues as of July 2026), it's the most popular agent orchestration framework in the ecosystem.
Installation¶
Via skills.sh (Recommended)¶
# Core ruflo skill only
npx skills add ruvnet/ruflo --skill ruflo --yes
# Full catalog — 267 skills across all 30+ plugins
npx skills add ruvnet/ruflo --all
Via npm¶
npm install -g ruflo
# or
npm install -g @claude-flow/cli
Initialize in a Project¶
# In your Hermes project root:
npx ruflo init
# Creates .claude/ directory, MCP config, hooks, and memory backend
# Auto-detects which agent you're using (Hermes, Codex, Claude Code, etc.)
Included Skills (Core)¶
| Skill | Installs | Purpose |
|---|---|---|
| ruflo | 2.0K | Core orchestration — swarms, memory, hooks, task lifecycle |
| agent-workflow | 1.3K | Multi-agent workflow coordination with hierarchical swarms |
| security-audit | 1.2K | Codebase security scans, CVE checks, adversarial testing |
| workflow-automation | 1.2K | Custom multi-step pipeline execution |
| memory-management | 1.1K | HNSW-indexed semantic search, hybrid SQLite+AgentDB backend |
30+ Plugins (Highlights)¶
| Plugin | Purpose |
|---|---|
ruflo-goals |
Deep research + goal-oriented action planning |
ruflo-cost-tracker |
Session cost telemetry, budgets, burn tracking |
ruflo-metaharness |
Harness scoring, MCP security scans, red/blue testing |
ruflo-browser |
Session-recorded browser automation with RVF replay |
ruflo-jujutsu |
Git diff risk analysis + PR lifecycle management |
ruflo-security-audit |
Codebase scans + CVE vulnerability checks |
Prerequisites¶
| Requirement | Details |
|---|---|
| Node.js | 20+ (verified by npx ruflo doctor) |
| npm | 9+ |
| MCP Server | Auto-configured by npx ruflo init |
| API Keys | Model provider keys as needed (Anthropic, OpenAI, etc.) |
Key Capabilities¶
1. Multi-Agent Swarms¶
Ruflo enables coordinated multi-agent execution with two topology modes:
- Hierarchical — orchestrator spawns and manages worker agents with anti-drift coordination
- Mesh — peer-to-peer agent communication with distributed task routing
# Initialize a swarm in the current project
npx ruflo init
# Spawn specialized agents via MCP
# mcp__claude-flow__agent_spawn — 55+ agent types (coder, reviewer, tester, security-architect, etc.)
2. Persistent Memory (HNSW Vector Search)¶
- Hybrid backend: SQLite + AgentDB
- HNSW-indexed semantic search across sessions
- Survives context window resets and model switches
# Store → Search → Retrieve pattern
# mcp__claude-flow__memory_store
# mcp__claude-flow__memory_search
# mcp__claude-flow__memory_retrieve
3. Self-Learning Intelligence Pipeline¶
4-step pipeline that runs continuously:
RETRIEVE → JUDGE → DISTILL → CONSOLIDATE
Captures patterns, learns from decisions, and improves agent selection over time.
4. Hooks & Observability¶
- Pre/post-edit hooks
- Session lifecycle events
- 12 built-in background workers
- Pattern-based agent selection
- 3-tier model routing (deterministic → Haiku → Sonnet/Opus)
5. Task Lifecycle Management¶
# mcp__claude-flow__task_create
# mcp__claude-flow__task_assign
# mcp__claude-flow__task_complete
# mcp__claude-flow__task_summary
Quick Start¶
# 1. Install globally
npm install -g ruflo
# 2. Initialize in your project
cd ~/your-hermes-project
npx ruflo init
# 3. Health check
npx ruflo doctor --fix
# 4. Discover matching plugins
npx ruflo discover-plugins
# 5. List all available MCP tools
npx ruflo mcp list
# 6. Check available plugins
npx ruflo plugins list
Verification¶
# Check version
npx ruflo --version
# Expected: 3.31.0+
# Health check
npx ruflo doctor
# Verify MCP tools registered
npx ruflo mcp list | head -20
# Check skills.sh install
npx skills list | grep ruflo
Hermes Integration Notes¶
- Ruflo auto-detects Hermes during
npx ruflo initand configures MCP accordingly - All 314+ MCP tools become available in Hermes as
mcp__claude-flow__* - Memory persistence survives Hermes context window resets
- SPARC methodology support for complex multi-step workflows
- GAIA benchmark runs for agent evaluation
Notes¶
- Production-grade: 65K GitHub stars, MIT license, v3.31.0 stable — not experimental
- Active: 822 open issues indicates heavy usage and rapid iteration
- Cross-agent: Works with 15+ coding agents, not locked to any single ecosystem
- When NOT to use: One-shot edits, simple bug fixes, single-agent tasks — the orchestration overhead isn't worth it for simple work
- Full docs: github.com/ruvnet/ruflo
- Related: See also Hermes Agent Setup for native Hermes orchestration