Claude-Flow / Ruflo — Summary

Claude-Flow (published to npm as claude-flow, GitHub repo renamed to ruvnet/ruflo) is an enterprise-grade multi-agent swarm orchestration platform for Claude Code and OpenAI Codex that lets developers deploy coordinated swarms of up to 60+ specialized AI agents against a shared memory store and MCP toolchain. It solves the problem of single-agent context limits and sequential task bottlenecks by providing a hierarchical coordinator-worker model, five swarm topologies (hierarchical, mesh, hierarchical-mesh, adaptive, flat), Byzantine fault-tolerant consensus strategies, and a persistent vector memory backend called AgentDB. What makes it distinct is the combination of SPARC methodology (a five-stage Specification → Pseudocode → Architecture → Refinement → Completion workflow), a built-in MCP server exposing 285–305 tools to the Claude Code session, and a hive-mind abstraction with queen/worker roles and Raft/CRDT/gossip consensus — none of which any comparable Claude Code framework ships together. It targets senior developers building complex multi-service systems who want fully automated agentic pipelines; however it carries a documented supply-chain security incident (Remote AI Behavior Injection via IPFS on the npm package) that raises production trust questions, making it best classified as a powerful but risk-stratified tool rather than a straightforward enterprise-ready platform.

Claude-Flow / Ruflo — Overview

Origin Story

Claude-Flow was created by ruvnet (Ruv, maintainer email ruv@ruv.io) and originally hosted at ruvnet/claude-flow. The repo was later renamed to ruvnet/ruflo while keeping the npm package name claude-flow and the binary name claude-flow. The homepage redirects to https://Cognitum.One/Consulting. The project began as a multi-agent orchestration framework for Claude Code and expanded over ~6,000+ commits (per CLAUDE.md: "6,000+ commits, 314 MCP tools, 16 agent roles + custom types") to include a full MCP server, a plugin ecosystem, a proprietary vector database (AgentDB / RuVector), and Codex CLI integration.

As of v3.10.1 (npm claude-flow@3.10.1), the project is a TypeScript monorepo with packages @claude-flow/cli, @claude-flow/mcp, @claude-flow/neural, @claude-flow/shared, @claude-flow/codex, and 21 native plugins.

Tagline / README Introduction

🌊 The leading agent orchestration platform for Claude. Deploy intelligent multi-agent swarms, coordinate autonomous workflows, and build conversational AI systems. Features enterprise-grade architecture, self-learning swarm intelligence, RAG integration, and native Claude Code / Codex Integration

Philosophy

The framework is built on a clear separation of concerns stated explicitly in AGENTS.md:

╔══════════════════════════════════════════════════════════════════╗
║  1. claude-flow = LEDGER (tracks state, stores memory, coordinates)
║  2. Codex = EXECUTOR (writes code, runs commands, creates files)
║  3. NEVER stop after calling claude-flow - IMMEDIATELY continue working
║  4. If you need something BUILT/EXECUTED, YOU do it, not claude-flow
║  5. ALWAYS search memory BEFORE starting: memory search --query "task"
║  6. ALWAYS store patterns AFTER success: memory store --namespace patterns
╚══════════════════════════════════════════════════════════════════╝

The CLAUDE.md configuration document reinforces a concurrency-first golden rule:

"1 MESSAGE = ALL RELATED OPERATIONS — All operations MUST be concurrent/parallel in a single message"

The architecture mandates:

• ALWAYS batch ALL todos in ONE TodoWrite call (5-10+ minimum)
• ALWAYS spawn ALL agents in ONE message with full instructions via Task tool
• ALWAYS batch ALL file reads/writes/edits in ONE message

Problem Framing

The framework addresses three core limitations of single-agent Claude Code sessions: context window exhaustion on large codebases, sequential (slow) execution, and lack of persistent memory across sessions. The solution is a three-tier routing model (WASM Agent Booster at <1ms for trivial transforms, Haiku at ~500ms for moderate tasks, Sonnet/Opus at 2-5s for complex reasoning) backed by a shared AgentDB SQLite/vector store that persists knowledge across sessions.

What We Believe

From CLAUDE.md:

"Follow Domain-Driven Design with bounded contexts. Keep files under 500 lines. Use typed interfaces for all public APIs. Prefer TDD London School (mock-first) for new code. Use event sourcing for state changes."

Claude-Flow / Ruflo — Architecture

Distribution Type

npm-package (also ships as a Claude Code plugin via .claude-plugin/)

Install Methods

# Primary: npx (no install required)
npx claude-flow@alpha init

# Specific version
npx claude-flow@3.10.1 init

# As plugin in Claude Code
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo

# As MCP server entry in .claude/settings.json
# (auto-configured on init)
{
  "mcpServers": {
    "claude-flow": {
      "command": "npx",
      "args": ["-y", "ruflo@latest", "mcp", "start"]
    }
  }
}

File / Directory Layout (Top-Level)

ruvnet/ruflo/
├── .agents/                    # Codex CLI skill definitions (107 SKILL.md files)
│   ├── config.toml             # Codex CLI configuration
│   ├── skills/                 # 107 agent skill directories
│   └── README.md
├── .claude/                    # Claude Code configuration
│   ├── settings.json           # Hooks, MCP servers, permissions, env vars
│   ├── agents/                 # Agent persona markdown files
│   ├── commands/               # Slash-command definitions (~160 .md files)
│   │   ├── sparc/              # SPARC methodology commands
│   │   ├── hive-mind/          # Hive-mind commands
│   │   ├── swarm/              # Swarm orchestration commands
│   │   ├── hooks/              # Hook commands
│   │   ├── memory/             # Memory commands
│   │   ├── github/             # GitHub integration commands
│   │   └── ...
│   └── helpers/                # hook-handler.cjs, auto-memory-hook.mjs, statusline.cjs
├── .claude-plugin/             # Claude Code plugin manifest
│   └── hooks/
│       └── hooks.json          # PreToolUse, PostToolUse, Stop hooks
├── plugins/                    # 32 native Ruflo plugins
│   ├── ruflo-agentdb/          # AgentDB memory substrate
│   ├── ruflo-sparc/            # SPARC methodology plugin
│   ├── ruflo-swarm/            # Swarm orchestration plugin
│   ├── ruflo-rag-memory/       # RAG + memory plugin
│   ├── ruflo-browser/          # Browser automation plugin
│   └── ...
├── v3/                         # TypeScript monorepo (v3 packages)
│   ├── @claude-flow/cli/       # CLI entry (49 commands)
│   ├── @claude-flow/mcp/       # MCP server (285-305 tools)
│   ├── @claude-flow/memory/    # AgentDB + HNSW search
│   ├── @claude-flow/neural/    # Neural coordination
│   ├── @claude-flow/hooks/     # 17 hooks + 12 workers
│   ├── @claude-flow/codex/     # Dual-mode Claude + Codex
│   ├── @claude-flow/guidance/  # Governance control plane
│   └── plugins/                # Plugin implementations (agentic-qe, gastown-bridge, etc.)
├── CLAUDE.md                   # Main configuration document
├── AGENTS.md                   # Codex-specific agent guidance
├── package.json                # npm package (name: claude-flow)
├── agentdb.rvf                 # AgentDB vector format file
└── verification/               # Baseline JSONs for MCP tool counts

Required Dependencies

• Node.js: 18+ (ESM modules)
• npm/npx: For package installation
• Claude Code CLI: Primary target (Claude Code with MCP support)
• OpenAI Codex CLI: Secondary target (via .agents/config.toml)

Optional runtime dependencies include:

• agentdb@^3.0.0-alpha.14 — vector + hierarchical memory store
• @ruvector/core, @ruvector/router — vector routing (RaBitQ WASM quantization)
• @ruvector/rabitq-wasm — 1-bit quantization (32× memory reduction)

Configuration Files

Claude-Flow / Ruflo — Components

Commands (Slash-Commands in .claude/commands/)

Count: ~160 command .md files across categories. Key commands by category:

SPARC Commands

Hive-Mind Commands

Swarm Commands

Coordination Commands

Hook Commands

Memory Commands

Other Key Commands

Skills (in .agents/skills/)

Count: 107 unique skill directories (107 SKILL.md files). Key named skills:

SPARC Methodology Skills: agent-specification, agent-pseudocode, agent-architecture, agent-refinement, agent-implementer-sparc-coder, agent-sparc-coordinator, sparc-methodology

Coordination Skills: agent-adaptive-coordinator, agent-byzantine-coordinator, agent-consensus-coordinator, agent-collective-intelligence-coordinator, agent-gossip-coordinator, agent-hierarchical-coordinator, agent-mesh-coordinator, agent-queen-coordinator, agent-v3-queen-coordinator, agent-coordinator-swarm-init, agent-coordination

Swarm Skills: agent-swarm, swarm-orchestration, swarm-advanced, agent-swarm-memory-manager, agent-multi-repo-swarm, agent-code-review-swarm, agent-release-swarm, agent-tdd-london-swarm

Memory Skills: agentdb-advanced, agentdb-learning, agentdb-memory-patterns, agentdb-optimization, agentdb-vector-search, agent-memory-coordinator, agent-v3-memory-specialist, memory-management, reasoningbank-agentdb, reasoningbank-intelligence

Developer Skills: agent-coder, agent-architect, agent-architecture, agent-planner, agent-goal-planner, agent-code-goal-planner, agent-code-analyzer, agent-analyze-code-quality, agent-tester, agent-reviewer, agent-researcher, agent-orchestrator-task, agent-worker-specialist

Operations Skills: agent-ops-cicd-github, agent-github-pr-manager, agent-github-modes, agent-release-manager, agent-issue-tracker, agent-project-board-sync, agent-sync-coordinator, agent-pr-manager, agent-swarm-pr, github-automation, github-code-review, github-release-management

Performance Skills: agent-performance-analyzer, agent-performance-benchmarker, agent-performance-monitor, agent-performance-optimizer, agent-matrix-optimizer, agent-pagerank-analyzer, performance-analysis, worker-benchmarks

Consensus Algorithm Skills: agent-raft-manager, agent-quorum-manager, agent-crdt-synchronizer, agent-load-balancer, agent-resource-allocator, agent-topology-optimizer

Specialized Skills: agent-neural-network, agent-safla-neural, agent-sona-learning-optimizer, flow-nexus-neural, neural-training, agent-trading-predictor, agent-agentic-payments, agent-payments, agent-authentication, agent-security-manager, agent-v3-security-architect, hive-mind, hive-mind-advanced

Subagents (Named Roles)

Count: 44 named agents in inventory (per verification/inventory.json). From .claude/agents/:

Key agent personas include: architect, coder, tester, reviewer, security-architect, database-specialist, swarm-memory-manager, memory-coordinator, coordinator, queen-coordinator, worker-specialist, performance-engineer, integration-architect, v3-queen-coordinator

From v3/plugins/gastown-bridge/agents/: architect.yaml, coder.yaml, reviewer.yaml, security-architect.yaml, tester.yaml

Hooks (Claude Code Hook Events)

Count: 7 distinct event types configured in .claude/settings.json

MCP Servers

Count: 1 bundled MCP server (claude-flow) exposing 285–305 tools (305 per verification/inventory.json as of latest; 285 per baseline from 2026-05-11)

MCP tool namespaces include: agentdb_* (15 tools), embeddings_* (10 tools), ruvllm_hnsw_* (3 tools), swarm management, memory operations, SPARC mode runners, agent spawning, performance analysis.

Scripts / Binaries

Claude-Flow / Ruflo — Uniqueness & Positioning

What Does This Do That No Other Seed Framework Does?

Claude-Flow combines five capabilities that no single comparable framework ships together:

1. A bundled MCP server with 285–305 tools exposing swarm management, agent lifecycle, memory operations, and SPARC mode-running as MCP tool calls — other frameworks configure Claude Code but do not ship an MCP server.

2. Byzantine fault-tolerant consensus strategies (raft, gossip, crdt, quorum, byzantine) for distributed agent coordination — no other framework in this set implements distributed systems consensus algorithms.

3. AgentDB: a proprietary hybrid vector + SQLite memory store with 29 named controllers, HNSW search, RaBitQ 1-bit quantization (32× memory reduction), causal graphs, and a hash-chained attestation log — purpose-built for multi-agent memory persistence.

4. 3-tier model routing dispatched at the UserPromptSubmit hook level: WASM Agent Booster (<1ms, $0) for trivial transforms, Haiku for moderate tasks, Sonnet/Opus for complex reasoning — cost optimization baked into the hook architecture, not left to the user.

5. Dual-mode Claude Code + Codex CLI orchestration with an explicit LEDGER/EXECUTOR division — claude-flow tracks state and memory while Codex or Claude Code does actual file operations, enabling cross-platform agent swarms that span both AI platforms.

What Does It Explicitly DROP That Others Have?

• No standalone IDE integration — no Cursor, Windsurf, or VS Code extension. Requires Claude Code or Codex CLI.
• No YAML/Gherkin spec format — specs are always Markdown. No structured test case syntax like Gherkin.
• No human-in-the-loop approval gates by default — auto-spawn-agents defaults to true, approval policy to on-request (not always). Heavy automation orientation.
• No monolithic CLAUDE.md methodology doc — the behavioral rules are distributed across CLAUDE.md, AGENTS.md, .claude/settings.json, and 107 SKILL.md files; there is no single document to read.

One-Sentence Positioning

Claude-Flow is the only Claude Code framework that ships a production multi-agent swarm runtime — including an MCP server, Byzantine fault-tolerant consensus, a vector memory database, and a five-phase SPARC workflow — as a single npx command.

Failure Modes / Criticisms

1. Supply-Chain Security Incident (CRITICAL)

From r/LocalLLaMA (1r8oehn):

"claude-flow npm package - Remote AI Behavior Injection via IPFS" / "Supply Chain Vulnerability in claude-flow npm"

A Reddit post documented a supply-chain vulnerability in the claude-flow npm package involving Remote AI Behavior Injection via IPFS. The mechanism: the npm package fetched or referenced content from IPFS (InterPlanetary File System) hashes, which allowed externally-hosted content to influence AI model behavior at runtime — a form of prompt injection via supply chain. This is a serious trust concern for any production deployment, as npm installs could pull in remotely-mutable AI behavior instructions.

The CLAUDE.md itself includes a security configuration (cveCheck: true, threatModel: true, autoScan: true) suggesting the maintainer is aware of security concerns, but the npm install path remains the primary distribution method.

2. "Not Fully Implemented" Criticism

From r/LocalLLaMA (1qnjota):

"claude-flow 'The leading agent orchestration platform for Claude' with 5.2k commits, but yeah, it's not fully implemented"

The framework's marketing ("leading agent orchestration platform," "enterprise-grade") outpaces reality. The graphAdapter controller is explicitly disabled in AgentDB pending an external graph-DB connection (ADR-095). Several alpha-tagged packages (agentdb@^3.0.0-alpha.14, @claude-flow/mcp@^3.0.0-alpha.8) indicate unstable APIs. The verification/mcp-tool-baseline.json note states "ADR-112 baseline — monotone decreasing for all three counts" suggesting tool counts are actively being reduced.

3. Complexity Overhead

107 SKILL.md files with acknowledged duplication (CLAUDE.md note: "repo has 367 SKILL.md files (5x duplicates of common skills) across .agents/skills, .claude/skills, archive/v2/.claude/skills, v3/@claude-flow/{cli,mcp}/.claude/skills") creates maintenance burden and Claude Code skill listing budget issues (addressed by bumping skillListingBudgetFraction to 0.06).

4. Star Count Inflation Concern

55,218 stars on a repo created 2025-06-02 (less than 12 months ago) with only 24 contributors is anomalous. Combined with the supply-chain incident, this raises questions about organic adoption vs. marketing-driven growth.

Competitors Named in README

(none explicitly named)

Inspired By

(not stated in source)