Claude Flow Tutorial 2025: Step-by-Step Setup Guide for AI Agent Orchestration

Introduction

Claude Flow is the leading agent orchestration platform for Claude, enabling you to deploy intelligent multi-agent swarms and coordinate autonomous workflows. With 8.8k GitHub stars and enterprise-grade architecture, it features distributed swarm intelligence, RAG integration, and native Claude Code support via MCP protocol.

Here's what makes Claude Flow powerful: 84.8% SWE-Bench solve rate, 32.3% token reduction, and 2.8-4.4x speed improvement through parallel coordination strategies. The platform includes 64 specialized agents and 87 MCP tools for comprehensive automation.

Quick Results:

• High SWE-Bench solve rate (industry-leading problem-solving)
• Substantial token reduction through efficient context management
• Multiple-fold speed improvement with parallel coordination
• Many specialized agents for complete development ecosystem

Note: Code examples in this article use Python and YAML for configuration. The concepts apply to any language or framework. For implementation guidance in TypeScript/JavaScript, refer to our Production-Ready AI Agent Architecture guide. For building video AI agents, see our Sora 2 Prompt Engineering guide.

This guide shows you exactly how to get started with Claude Flow, from installation to building your first multi-agent system.

What You'll Learn:

• Complete Claude Flow setup and configuration
• How to spawn and manage AI agents
• Building automated workflows with Hooks
• Advanced SPARC methodology for structured development
• HIVE-MIND coordination for complex multi-agent projects
• Practical examples and real-world use cases

Pro-Tip: Claude Flow implements multi-agent orchestration patterns and uses Model Context Protocol (MCP) for tool integration. For production deployments, follow production-ready AI agent architecture best practices. For understanding context engineering, see our Context Engineering vs Prompt Engineering guide.

What is Claude Flow?

Claude Flow is an advanced agent orchestration platform that enables you to deploy, coordinate, and manage multiple AI agents working together on complex development tasks. Unlike traditional single-model approaches, Claude Flow creates intelligent swarms that coordinate specialized agents, share context and memory across interactions, automate complex workflows through intelligent task delegation, and scale from simple scripts to enterprise applications.

1. Getting Started with Claude Flow

Claude Flow enables you to:

• Coordinate multiple specialized agents for different aspects of a project
• Share context and memory across agent interactions
• Automate complex workflows through intelligent task delegation
• Scale from simple scripts to enterprise applications

1.1 Key Features

1.2 How Claude Flow Works

Claude Flow operates on a swarm intelligence model where:

1. Orchestrator manages the overall workflow and task distribution (see AI agent orchestration guide for patterns)
2. Specialized Agents handle specific aspects (coding, testing, documentation)
3. Memory System maintains context and learning across interactions (see memory and context management for advanced patterns)
4. Hooks System automates repetitive tasks and quality checks

2. Prerequisites and System Requirements

Before installing Claude Flow, ensure your system meets these requirements:

2.1 System Requirements

• Node.js: Version 18 or higher
• npm: Version 9 or higher
• Operating System: Windows 10+, macOS 10.15+, or Linux (Ubuntu 18.04+)
• Memory: Minimum 4GB RAM (8GB recommended for complex workflows)
• Storage: 2GB free space for installation and dependencies

2.2 Required Dependencies

• Claude Code: Must be installed globally before Claude Flow
• Git: For version control and project management
• Terminal/Command Line: Access to command line interface

2.3 Network Requirements

• Internet Connection: Required for initial installation and updates
• Port Access: Claude Flow may require specific ports for agent communication
• Firewall Settings: Ensure Claude Flow can communicate with external services

3. Complete Installation Guide

3.1 Step 1: Install Claude Code

Claude Flow requires Claude Code as a prerequisite. Install it globally:

# Install Claude Code globally
npm install -g @anthropic-ai/claude-code

# Verify installation
claude --version

Important: After installation, you need to activate Claude Code with the necessary permissions:

# Activate Claude Code (required for MCP integration)
claude --dangerously-skip-permissions

3.2 Step 2: Install Claude Flow

Install the latest version of Claude Flow globally:

# Install Claude Flow (using the official package)
npm install -g claude-flow@alpha

# Verify installation
claude-flow --version

3.3 Step 3: Initialize Claude Flow

Initialize Claude Flow with the recommended configuration:

# Initialize Claude Flow (creates necessary directories and configs)
npx claude-flow@alpha init --force

This command creates the necessary configuration files and directories:

• .hive-mind/ - Contains config.json + SQLite session data
• .swarm/ - Contains memory.db (SQLite database)
• memory/ - Agent-specific memories (created when agents spawn)
• coordination/ - Active workflow files (created during tasks)

3.4 Step 4: Configure MCP Server

Add Claude Flow as an MCP server to Claude Code:

# Add Claude Flow as MCP server
claude mcp add claude-flow npx claude-flow@alpha mcp start

# Verify MCP server is added
claude mcp list

4. Configuration and Setup

4.1 Memory System Configuration

Claude Flow uses a sophisticated memory system for context sharing between agents:

# Check memory statistics
npx claude-flow@alpha memory stats

# List stored contexts
npx claude-flow@alpha memory list

# Query recent memory
npx claude-flow@alpha memory query --recent --limit 5

4.2 Hooks System Setup

Hooks are automatically configured during initialization, but you can check their status:

# Check hook status
npx claude-flow@alpha hooks status

# Enable specific hooks
npx claude-flow@alpha hooks enable --all

4.3 System Configuration

Claude Flow automatically configures optimal settings, but you can monitor system status:

# Check overall system status
npx claude-flow@alpha status

# Monitor Hive-Mind status
npx claude-flow@alpha hive-mind status

# View active sessions
npx claude-flow@alpha hive-mind sessions

5. Basic Usage and Commands

5.1 System Status and Monitoring

Check the overall system status:

# Display orchestrator status, active agents, and memory usage
npx claude-flow@alpha status

# Get detailed system information
npx claude-flow@alpha memory stats

# Monitor real-time agent activity
npx claude-flow@alpha hive-mind status

5.2 Hive-Mind Management

Spawn and manage Hive-Mind swarms:

# Spawn a Hive-Mind for a specific task
npx claude-flow@alpha hive-mind spawn "Implement user authentication" --claude

# Check Hive-Mind status
npx claude-flow@alpha hive-mind status

# List all sessions
npx claude-flow@alpha hive-mind sessions

# Resume a specific session
npx claude-flow@alpha hive-mind resume session-xxxxx-xxxxx

5.3 Swarm Coordination

Coordinate multiple agents for complex tasks:

# Create a swarm for building a REST API
npx claude-flow@alpha swarm "Build a REST API with authentication" --max-agents 5 --parallel

# Continue working on the same feature (reuse existing hive)
npx claude-flow@alpha swarm "Add password reset functionality" --continue-session

# Monitor swarm progress
npx claude-flow@alpha swarm status

6. Practical Examples and Use Cases

6.1 Example 1: Building a React Todo App

Create a complete React application with multiple agents:

# Spawn a swarm for React development
npx claude-flow@alpha swarm "Create a React todo app with TypeScript, Tailwind CSS, and local storage persistence. Include add, edit, delete, and filter functionality." --max-agents 4

What happens:

• Frontend Agent: Creates React components and UI
• Styling Agent: Implements Tailwind CSS styling
• Logic Agent: Handles state management and local storage
• Testing Agent: Writes unit tests and integration tests

6.2 Example 2: API Backend Development

Build a Node.js Express API with authentication:

# Create API development swarm
npx claude-flow@alpha swarm "Build an Express.js API with JWT authentication, user registration, login, password hashing with bcrypt, and protected routes." --max-agents 5

Agent roles:

• Backend Agent: Sets up Express server and routes
• Auth Agent: Implements JWT authentication
• Security Agent: Handles password hashing and validation
• Database Agent: Creates database schemas and migrations
• Documentation Agent: Generates API documentation

6.3 Example 3: Data Analysis Pipeline

Analyze data with specialized agents:

# Create data analysis swarm
npx claude-flow@alpha swarm "Analyze customer data, identify trends, and generate business insights with visualizations" --max-agents 3

Workflow:

1. Data Agent: Cleans and preprocesses data
2. Analysis Agent: Performs statistical analysis
3. Visualization Agent: Creates charts and reports

7. Advanced Features: Hooks, SPARC, and HIVE-MIND

7.1 Advanced Hooks System

Claude Flow v2.0.0 introduces a powerful hooks system that automates coordination and enhances every operation:

Hooks are automatically configured during initialization:

# Initialize with hooks enabled
npx claude-flow@alpha init --force  # Auto-configures MCP servers & hooks

# Check hook status
npx claude-flow@alpha hooks status

7.2 SPARC: Structured AI Development Methodology

SPARC (Specification, Pseudocode, Architecture, Refinement, and Completion) is Claude Flow's structured approach to AI-driven development. It breaks down complex projects into manageable phases with intelligent coordination.

SPARC Phases Explained

Using SPARC Modes

Claude Flow offers specialized SPARC modes for different development needs:

# List all available SPARC modes
npx claude-flow@alpha sparc modes

# Test-Driven Development mode
npx claude-flow@alpha sparc run tdd "user authentication system"

# API development mode
npx claude-flow@alpha sparc run api "REST API for e-commerce"

# UI development mode
npx claude-flow@alpha sparc run ui "React dashboard with analytics"

# Full-stack development mode
npx claude-flow@alpha sparc run dev "complete web application"

# Refactoring mode
npx claude-flow@alpha sparc run refactor "legacy codebase modernization"

SPARC Workflow Example

# Start a complete SPARC workflow for a project
npx claude-flow@alpha sparc run dev "Build a task management system with real-time collaboration"

# Monitor SPARC progress
npx claude-flow@alpha sparc status

# Get detailed phase information
npx claude-flow@alpha sparc phase --current

7.3 HIVE-MIND: Advanced Multi-Agent Coordination

HIVE-MIND represents Claude Flow's most advanced orchestration system, enabling persistent, hierarchical coordination for complex, long-running projects. It simulates collective intelligence with specialized agent roles.

HIVE-MIND Architecture

Queen Agent (Coordinator)
├── Architect Agent (System Design)
├── Developer Agent (Code Implementation)
├── Tester Agent (Quality Assurance)
├── Documentation Agent (Knowledge Management)
└── DevOps Agent (Deployment & Operations)

Key HIVE-MIND Features

Initializing HIVE-MIND

# Initialize HIVE-MIND with mesh topology
npx claude-flow@alpha hive-mind init --topology mesh --agents 5

# Check HIVE-MIND status
npx claude-flow@alpha hive-mind status

# Monitor agent coordination
npx claude-flow@alpha hive-mind monitor

# View collective memory
npx claude-flow@alpha memory list

HIVE-MIND Orchestration

# Orchestrate complex tasks with HIVE-MIND
npx claude-flow@alpha hive-mind spawn "Build a microservices architecture with authentication, payment processing, and real-time notifications" --agents 5 --parallel

# Resume interrupted HIVE-MIND session
npx claude-flow@alpha hive-mind resume session-xxxxx-xxxxx

# Create HIVE-MIND checkpoint
npx claude-flow@alpha hive-mind checkpoint --name "milestone_v1"

8.3 Combining SPARC and HIVE-MIND

The true power of Claude Flow emerges when you combine SPARC's structured methodology with HIVE-MIND's advanced coordination:

# SPARC-driven HIVE-MIND orchestration
npx claude-flow@alpha hive-mind spawn "SPARC: Build enterprise CRM system" --method sparc --agents 6

# Monitor combined workflow
npx claude-flow@alpha status --show-sparc --show-hive-mind

# Get detailed coordination report
npx claude-flow@alpha report --comprehensive

Advanced Configuration

# Configure HIVE-MIND consensus thresholds
npx claude-flow@alpha hive-mind config set consensus.threshold 0.8
npx claude-flow@alpha hive-mind config set consensus.timeout 300

# Set SPARC phase timeouts
npx claude-flow@alpha sparc config set phase.timeout 600
npx claude-flow@alpha sparc config set refinement.retries 3

# Enable advanced memory sharing
npx claude-flow@alpha hive-mind config set memory.sharing true
npx claude-flow@alpha hive-mind config set memory.retention 7d

8.4 Practical Example: Enterprise Application with SPARC + HIVE-MIND

Let's build a complete enterprise application using both SPARC and HIVE-MIND:

# Step 1: Initialize HIVE-MIND for the project
npx claude-flow@alpha hive-mind init --topology mesh --agents 6 --project "enterprise-crm"

# Step 2: Start SPARC-driven development
npx claude-flow@alpha sparc run dev "Build enterprise CRM with user management, sales pipeline, and analytics dashboard"

# Step 3: Monitor the combined workflow
npx claude-flow@alpha status --show-sparc --show-hive-mind --detailed

What happens during execution:

1. SPARC Specification Phase: Requirements Agent analyzes CRM needs
2. SPARC Architecture Phase: Architect Agent designs microservices architecture
3. HIVE-MIND Coordination: Queen Agent distributes tasks to specialized workers
4. Parallel Development: Multiple agents work on different components simultaneously
5. Consensus Building: Agents collaborate on integration points
6. SPARC Refinement: Tester Agent ensures quality through TDD
7. SPARC Completion: DevOps Agent handles deployment and monitoring

Advanced Monitoring and Control

# Monitor HIVE-MIND consensus building
npx claude-flow@alpha hive-mind consensus --watch

# Check SPARC phase progress
npx claude-flow@alpha sparc phase --detailed --watch

# Get comprehensive project report
npx claude-flow@alpha report --project "enterprise-crm" --format json

# Create project checkpoint
npx claude-flow@alpha hive-mind checkpoint create --name "architecture-complete" --description "Microservices architecture designed and approved"

8. Best Practices and Workflows

8.1 New to Claude-Flow? Start Here!

Confused about .hive-mind and .swarm directories? Not sure when to create new hives? Here are the most common workflow patterns:

🚀 Pattern 1: Single Feature Development

# Initialize once per feature/task
npx claude-flow@alpha init --force
npx claude-flow@alpha hive-mind spawn "Implement user authentication" --claude

# Continue working on SAME feature (reuse existing hive)
npx claude-flow@alpha hive-mind status
npx claude-flow@alpha memory query "authentication" --recent
npx claude-flow@alpha swarm "Add password reset functionality" --continue-session

🏗️ Pattern 2: Multi-Feature Project

# Project-level initialization (once per project)
npx claude-flow@alpha init --force --project-name "my-app"

# Feature 1: Authentication (new hive)
npx claude-flow@alpha hive-mind spawn "auth-system" --namespace auth --claude

# Feature 2: User management (separate hive)  
npx claude-flow@alpha hive-mind spawn "user-management" --namespace users --claude

# Resume Feature 1 later (use session ID from spawn output)
npx claude-flow@alpha hive-mind resume session-xxxxx-xxxxx

🔍 Pattern 3: Research & Analysis

# Start research session
npx claude-flow@alpha hive-mind spawn "Research microservices patterns" --agents researcher,analyst --claude

# Continue research in SAME session
npx claude-flow@alpha memory stats  # See what's been learned
npx claude-flow@alpha swarm "Deep dive into API gateway patterns" --continue-session

8.2 When Should I Create a New Hive?

8.3 Understanding "Empty" Directories

Don't panic if directories seem empty! Claude-Flow uses SQLite databases that may not show files in directory listings:

# Check what's actually stored (even if directories look empty)
npx claude-flow@alpha memory stats        # See memory data
npx claude-flow@alpha memory list         # List all namespaces  
npx claude-flow@alpha hive-mind status    # See active hives

Your project structure after initialization:

• .hive-mind/ - Contains config.json + SQLite session data
• .swarm/ - Contains memory.db (SQLite database)
• memory/ - Agent-specific memories (created when agents spawn)
• coordination/ - Active workflow files (created during tasks)

8.4 Continuing Previous Work

# See what you were working on
npx claude-flow@alpha hive-mind status
npx claude-flow@alpha memory query --recent --limit 5

# List all sessions to find the one you want
npx claude-flow@alpha hive-mind sessions

# Resume specific session by ID
npx claude-flow@alpha hive-mind resume session-xxxxx-xxxxx

9. Troubleshooting and Integration

9.1 Common Issues and Solutions

Installation Problems:

# Clear npm cache and retry
npm cache clean --force
npm install -g claude-flow@alpha

Session Issues:

# Check session status and resume
npx claude-flow@alpha hive-mind sessions
npx claude-flow@alpha hive-mind resume session-xxxxx-xxxxx

Performance Issues:

• Check system status: npx claude-flow@alpha status
• Monitor memory usage: npx claude-flow@alpha memory stats
• Check active sessions: npx claude-flow@alpha hive-mind status

9.2 Integration with Existing Workflows

Claude Code Integration:

# Use Claude Flow within Claude Code
claude "Create a React component using Claude Flow agents"

CI/CD Integration:

# Add to package.json scripts
{
  "scripts": {
    "claude-flow:test": "npx claude-flow@alpha swarm 'Run all tests' --max-agents 2",
    "claude-flow:build": "npx claude-flow@alpha swarm 'Build production bundle' --max-agents 3"
  }
}

9.3 Best Practices

• Start Small: Begin with 2-3 agents and scale gradually
• Monitor Performance: Use npx claude-flow@alpha status regularly
• Session Management: Resume previous sessions instead of starting new ones
• Memory Management: Track usage with npx claude-flow@alpha memory stats

Conclusion

Claude Flow transforms AI development by enabling multiple specialized agents to work together on complex tasks. By following this guide, you've learned how to install, configure, and use Claude Flow for building sophisticated AI-powered applications.

Your next steps:

1. Week 1: Complete the installation and run your first simple agent
2. Week 2: Experiment with swarms and multi-agent workflows
3. Week 3: Integrate Claude Flow with your existing development projects
4. Week 4: Master SPARC methodology and HIVE-MIND coordination for enterprise projects

Key success metrics to track:

• Agent response time (target: fast response times)
• Task completion rate (target: high completion rates)
• Memory efficiency (target: efficient memory usage)
• Workflow automation (target: substantial reduction in manual tasks)

Claude Flow enables you to build AI systems that think, collaborate, and scale beyond single-model limitations. Start with simple agents, gradually add complexity, and watch your development productivity soar.

Further Reading

• Cursor Rules: 10x Productivity with Cursor Rules, Context & Automation
• Context Engineering vs Prompt Engineering: The 2025 Guide
• AI Agent Orchestration: Building Multi-Agent Systems That Actually Work in 2025
• Model Context Protocol (MCP): A Simple Guide to the 'USB-C' of AI Apps
• Official Claude Flow GitHub Repository - 8.8k stars, comprehensive documentation
• Claude Flow Wiki - Complete documentation and guides
• Claude Flow Discord Community - Join the Agentics Foundation community

Need hands-on help? Head over to our AI Consulting page and schedule a call.