How ruvnet/claude-flow works
Project Type and Purpose
• Claude-Flow v2.0.0 Alpha is an enterprise-grade AI orchestration platform: a monorepo combining a rich CLI, core libraries, an event-driven coordination engine (“hive-mind”), distributed memory, neural tooling, MCP services, web and console UIs, and integration hooks.
• It’s a developer toolchain rather than a traditional webapp, organized as a full-stack application (CLI front-end + core “backend” libraries + optional UIs).
High-Level File Structure Analysis
• Top-level modules:
• /bin & /src/cli → Command-line interface, command registry, scripts.
• /src/core, /src/coordination, /src/swarm, /src/task → Event-bus, orchestrator, task scheduling, swarm orchestration libraries.
• /src/agents & /src/hive-mind → Queen + worker agent implementations and communication protocols.
• /src/memory & /memory → Distributed memory manager, backends (SQLite, markdown), cache, replication.
• /src/mcp → MCP server, transports (HTTP/STDIO), protocol manager for tool integration.
• /src/ui/console & /src/ui/web-ui → Console-based and web-based user interfaces.
• /scripts, /.claude/hooks → Build/test scripts and hooks system.
• /infrastructure/docker → Docker-based deployment of Hive-Mind DB and MCP servers.
README Insights
• The architecture overview lists these logical layers:
• Hive-Mind Coordination Layer (Queen + worker agents)
• Neural Pattern Recognition Layer
• Distributed Memory System
• 87 MCP Tools Integration Layer
• Claude Code Integration Layer
• Key tech: Node.js/TypeScript, WASM for neural acceleration, SQLite for persistence, pub/sub event bus, Cliffy CLI framework, Docker.
Main Components
a. CLI Front-End:
• Input: bin scripts, src/cli modules
• Interacts via Command Registry → Core Orchestrator
b. Core Orchestration Engine:
• src/core/event-bus, orchestrator, json-persistence, logger
• Publishes tasks to Coordination Manager
c. Coordination Layer:
• src/coordination: scheduler, swarm-coordinator, load-balancer, messaging
• Implements hierarchical, mesh, hybrid strategies
d. Agent Framework (Hive-Mind):
• src/hive-mind/core: Queen, Agents, MemoryMonitor, Communication
• src/agents: agent registry, manager
e. Task Execution (Swarm):
• src/swarm: executors, optimizations, prompt manager
f. Memory & Persistence:
• src/memory + /memory package: backends, cache, indexer, replication
• Hive-Mind DB (SQLite) under .hive-mind
g. Neural/Pattern Layer:
• WASM modules invoked by CLI & core for pattern training/prediction
h. MCP Services:
• src/mcp: HTTP/STDIO transports, protocol management, session manager
i. UI Layers:
• Console UI: websockets via src/ui/console/js
• Web UI: React-style components under src/ui/web-ui using EventBus & MCPIntegrationLayer
j. External Integrations:
• GitHub (via src/cli/commands/github), Docker, filesystems, network
Relationships & Data Flow
1. User issues a CLI command → CLI front-end parses & routes to Command Registry.
2. CLI invokes Core Orchestrator → emits events on Event Bus.
3. Coordination Manager subscribes → schedules tasks via Swarm or Hive-Mind layers.
4. Queen Agent spawns worker Agents → Agents execute tasks using Swarm executors or MCP Tools.
5. Agents read/write from Distributed Memory and Hive-Mind DB.
6. Neural modules may be invoked for pattern recognition/training via WASM.
7. Results aggregated by Core’s Result Aggregator → CLI prints or pushes updates to UIs.
8. CLI/UI can connect to MCP Server for programmatic integrations.
Architectural Patterns & Principles
• Layered architecture: CLI → Core → Coordination → Agents → Memory/DB
• Event-driven & pub/sub: event-bus, message-bus
• Plugin‐based CLI: each command is a module under src/cli/commands
• Hexagonal boundaries: core libraries are decoupled from transport & persistence
• Microservices‐style “modules” (Memory, MCP, Hive-Mind) communicating via interfaces