Claude-Flow: The Actually Practical Guide

Claude-Flow Architecture Infographic

Complete setup guide from zero to multi-agent orchestration

What Is This?

Claude-flow turns Claude Code into a multi-agent orchestration system. You can spawn AI agents, create tasks, store patterns in memory, and build complex workflows — all from a normal conversation with Claude.

This guide covers everything from installation to daily usage.

Prerequisites

Before starting, make sure you have:

Node.js 18+ installed
Claude Code CLI installed (get it from claude.ai/download) Verify both:

node --version  # Should show v18 or higher
claude --version  # Should show Claude Code CLI version

Step 1: Install Claude-Flow (Once Per Machine)

Install the CLI globally:

npm install -g @claude-flow/cli@latest

Verify it installed correctly:

claude-flow --version

You should see a version number (e.g., 3.x.x).

To update later:

npm update -g @claude-flow/cli

Step 2: Connect to Claude Code (Once Per Machine)

This connects claude-flow tools to your Claude Code sessions:

claude mcp add claude-flow -- claude-flow mcp start

Verify it's connected:

claude mcp list

You should see claude-flow listed as connected (green checkmark or "✓").

What this does: Registers claude-flow as an MCP (Model Context Protocol) server that Claude Code can talk to.

Step 3: Per-Project Setup

Navigate to your project and create a .mcp.json file in the root:

cd /path/to/your/project

Create .mcp.json:

{
  "mcpServers": {
    "claude-flow": {
      "command": "claude-flow",
      "args": ["mcp", "start"],
      "env": {
        "CLAUDE_FLOW_MODE": "v3",
        "CLAUDE_FLOW_HOOKS_ENABLED": "true",
        "CLAUDE_FLOW_TOPOLOGY": "hierarchical-mesh",
        "CLAUDE_FLOW_MAX_AGENTS": "15",
        "CLAUDE_FLOW_MEMORY_BACKEND": "hybrid"
      }
    }
  }
}

What this does: Tells Claude Code to load claude-flow when you open this project.

Step 4: Initialize the Project

Still in your project directory, run:

claude-flow init

What this creates:

your-project/
├── .claude-flow/          # Runtime data
│   ├── config.json        # Project settings
│   ├── data/              # Memory storage
│   └── sessions/          # Saved sessions
└── .claude/
    └── settings.json      # Hook configuration

What starts running (behind the scenes):

MCP server
Memory backend (sql.js + vector search)
26 hooks
12 background workers (idle until needed)
Intelligence layer (SONA, MoE routing) What does NOT happen:
No agents spawn
No tasks created
Memory is empty
Nothing happens until you tell it to

Step 5: Health Check

Verify everything is working:

claude-flow doctor --fix

Expected output:

✅ Swarm: healthy
✅ Memory: healthy
✅ MCP: healthy
✅ Neural: healthy
✅ Disk: healthy
✅ Network: healthy
✅ Database: healthy
 
All systems operational (7/7)

If anything shows unhealthy, the --fix flag will attempt to repair it automatically.

Step 6: Open Claude Code

Now open Claude Code in your project:

claude

Or open Claude Code and navigate to your project folder.

Behind the scenes (automatic):

MCP server starts
Memory backend loads
Hooks activate
Workers stand ready
Intelligence layer initializes What you'll see: Just normal Claude Code, ready for your first command.

Your First Session (Copy-Paste This)

In Claude Code conversation, paste:

Run claude-flow doctor fix, start a session called "my-project",
set topology to hierarchical with 8 max agents,
and pretrain on this codebase.

What this does:

✅ Double-checks system health
📂 Creates a session that saves your work
🔀 Sets up hierarchical agent structure (one lead, many workers)
🧠 Scans your codebase to learn patterns You'll see responses confirming each step. Now you're ready to work.

Basic Commands (Just Talk to Claude)

You don't need to memorize tool names. Just talk naturally:

Check Status

"Show me the swarm status"
"List all active agents"
"What's in memory?"
"Show me all tasks"

Spawn Agents

"Spawn a coder agent to build the login page"
"Create a reviewer agent to check my PR"
"Spawn a security architect to audit the auth system"

Create Tasks

"Create a high-priority feature task: Add dark mode"
"Create a bug task: Fix memory leak in session handler"
"Make a testing task for the payment API"

Store in Memory

"Store this pattern: React components use hooks for state"
"Remember that we use JWT with refresh tokens for auth"
"Save this: Database uses PostgreSQL 14 with TimescaleDB"

Search Memory

"Search memory for authentication patterns"
"What do we know about error handling?"
"Find everything about database design"

Checking If Everything Works

After your first session setup, verify each system:

1. Health Check

"Run a health check"

Should show:

✅ Swarm: healthy
✅ Memory: healthy
✅ MCP: healthy
✅ Neural: healthy
✅ Disk: healthy
✅ Network: healthy
✅ Database: healthy

2. Memory System

"Store a test pattern in memory"
"Search memory for test"
"List everything in memory"

Should return your test data.

3. Agent System

"Spawn a test coder agent"
"List all agents"
"Check agent health"
"Terminate that agent"

Should spawn, list, and terminate successfully.

4. Task System

"Create a test task"
"List all tasks"
"Complete that task"

Should create and manage tasks.

5. Intelligence Layer

"What agent type should I use for fixing a memory leak?"
"Route this task: Add user authentication"

Should recommend agent types intelligently.

6. Session Persistence

"Save the session"
"End the session"

Then close Claude Code, reopen it, and:

"Restore my session"

Should reload everything (agents, tasks, memory).

Real-World Workflows

Solo Coding

You: "Start a session called 'dark-mode-feature'"
You: "Create a feature task: Implement dark mode toggle"
You: "Spawn a coder agent to work on it"
 
[Work with the agent through conversation]
 
You: "Store this pattern: Dark mode uses CSS variables in :root"
You: "Save and end the session"

Multi-Agent Team

You: "Start session 'api-build'"
You: "Initialize a swarm with hierarchical topology, max 5 agents"
You: "Create these tasks:
      - Build REST API endpoints (high priority)
      - Write comprehensive tests (high priority)  
      - Update API documentation (normal priority)"
You: "Spawn three agents:
      - Coder for the API endpoints
      - Tester for the test suite
      - Coder for documentation"
 
[Agents work, you review outputs]
 
You: "Save session and shut down the swarm"

Code Review Pipeline

You: "Start session 'pr-review'"
You: "Spawn a reviewer agent to analyze PR #42"
You: "Spawn a security architect to audit PR #42"
 
[Review findings from both agents]
 
You: "Store findings in memory under 'code-review-patterns'"
You: "End session"

Research Then Build

You: "Start session 'oauth-implementation'"
You: "Spawn a researcher agent to research OAuth2.0 best practices"
 
[Wait for research results]
 
You: "Store the research findings in memory"
You: "Spawn a coder agent to implement OAuth2 based on research"
You: "Spawn a tester to write OAuth2 tests"
You: "End session"

Understanding Agent Types

You have 50+ specialized agents. Most common:

Just ask:

"What agent types are available?"
"Recommend an agent for database optimization"

Memory System Explained

Memory is your persistent knowledge base across sessions.

Store Patterns

"Store this: API rate limiting uses token bucket algorithm"
"Remember: Production database is PostgreSQL 15"
"Save pattern: Error handling wraps all async operations in try-catch"

Search Semantically

"Search memory for database"
"What do we know about error handling?"
"Find authentication patterns"

Organize by Namespace

"Store in patterns namespace: React components use functional style"
"Store in architecture namespace: Microservices communicate via gRPC"
"List everything in patterns namespace"

Topology Explained

Topology controls how agents coordinate:

Hierarchical (Recommended for Most Projects)

"Set topology to hierarchical with max 8 agents"

One lead agent coordinates workers. Best for standard development.

Mesh (Equal Collaboration)

"Set topology to mesh with max 6 agents"

All agents collaborate as peers. Good for research/exploration.

Star (Single Coordinator)

"Set topology to star with max 10 agents"

Hub-and-spoke pattern. Good for centralized control.

Ring (Sequential Pipeline)

"Set topology to ring with max 5 agents"

Pipeline processing. Good for data processing workflows.

Background Workers (Automatic)

These run automatically when triggered:

You can also trigger manually:

"Run an audit worker on the auth directory"
"Map the entire codebase"
"Find test coverage gaps"

Troubleshooting

"No tools available"

claude mcp list

If claude-flow is missing:

claude mcp add claude-flow -- claude-flow mcp start

"System unhealthy"

claude-flow doctor --fix

Or in Claude Code:

"Run doctor fix"

"No agents available"

Agents don't auto-start. Spawn them:

"Spawn a coder agent"

"Memory is empty"

Memory starts empty. Either:

Run pretrain: "Pretrain on this codebase"
Store manually: "Store this pattern: ..."

"Can't restore session"

Must save before restoring:

"Save the session"

Then later:

"Restore my session"

".mcp.json not loading"

Make sure:

File is in project root
JSON is valid (use a linter)
Restart Claude Code after creating it

Daily Workflow

Morning (Starting Work)

# Open Claude Code in your project
cd /path/to/project
claude

Then in Claude Code:

"Restore my claude-flow session"

During Work

"Spawn agents as needed"
"Create tasks"
"Store learnings in memory"

Evening (Ending Work)

"Save and end the session"

Configuration

Increase Agent Limit

"Set max agents to 15"

Increase Memory Capacity

"Set memory max entries to 50000"

Enable Verbose Logging

"Set logging level to debug"

View Current Settings

"Show me the current configuration"

What You Actually Get

Instead of:

Writing code alone
Context switching between tasks
Forgetting patterns
Redoing research
Manual code reviews You get:
Multiple specialized AI agents working in parallel
Persistent memory across sessions
Intelligent task routing
Automated background work (audits, mapping, optimization)
Learning system that improves over time

Quick Reference Card

System Health

"Run health check"
"Show swarm status"

Sessions

"Start session 'name'"
"Save session"
"Restore session"
"End session"

Agents

"Spawn [type] agent to [task]"
"List all agents"
"Terminate agent-123"

Tasks

"Create [type] task: [description]"
"List all tasks"
"Complete task-123"

Memory

"Store: [pattern]"
"Search memory for [query]"
"List memory"

Intelligence

"Route this task: [description]"
"Recommend agent for [task]"

Workers

"Run [worker] on [context]"
"Show worker status"

The Mental Model

Think of claude-flow as hiring a team:

Session = Starting your workday
Swarm = Your team structure
Agents = Individual team members
Tasks = Work items on the board
Memory = Shared knowledge base
Intelligence = Smart task assignment
Workers = Background support staff You're the manager. Claude-flow is the infrastructure. The agents are the workers.

Quick Setup Checklist

One-time setup (per machine):

Per project:

Next Steps

Now that you know the basics:

Experiment with agents: Try different agent types for different tasks
Build up memory: Store every useful pattern you discover
Try multi-agent workflows: See what parallel work looks like
Explore background workers: Let automation handle routine tasks
Monitor learning: Check intelligence status periodically The system improves as you use it. More patterns stored = better routing. More trajectories completed = smarter recommendations.

TL;DR: Install → Connect → Init → Open Claude Code → Talk normally → Get multi-agent orchestration. That's it.