v2/docs/guides/USER_GUIDE.md
Welcome to the comprehensive user guide for Claude-Flow! This document provides everything you need to get started and master the platform, from basic installation to advanced swarm coordination.
Before starting with Claude-Flow, ensure you have:
# Option 1: Use npx (recommended for first-time users)
npx claude-flow@alpha --help
# Option 2: Global installation
npm install -g claude-flow@alpha
# Option 3: Project-specific installation
npm install claude-flow@alpha
# Initialize Claude-Flow in your project
npx claude-flow@alpha init --force
# Verify installation
npx claude-flow@alpha version
# Run health check
npx claude-flow@alpha health
Try your first Claude-Flow command:
# Simple task execution
npx claude-flow@alpha swarm "create a simple Hello World application"
AI-powered workers that perform specific tasks:
Groups of agents working together:
Persistent knowledge storage:
Model Context Protocol tools:
| Category | Examples | Use Cases |
|---|---|---|
| Development | coder, reviewer, tester | Code implementation, quality assurance |
| Architecture | architect, planner | System design, project planning |
| Specialized | backend-dev, mobile-dev, ml-developer | Domain-specific development |
| Coordination | coordinator, monitor | Task management, progress tracking |
| Analysis | researcher, analyzer | Information gathering, code analysis |
๐ Queen
/ | \
๐ ๐ ๐
๐ --- ๐
/\ /\
๐ ๐ ๐ ๐
๐ โโโ ๐
โ โฒ โฑ โ
โ โณ โ
โ โฑ โฒ โ
๐ โโโ ๐
๐
/ \
๐ ๐
/ \ / \
๐ ๐ ๐ ๐
For straightforward development tasks:
# Code generation
npx claude-flow@alpha swarm "create a REST API for user management"
# Bug fixing
npx claude-flow@alpha swarm "fix all TypeScript errors in the project"
# Documentation
npx claude-flow@alpha swarm "generate comprehensive API documentation"
# Testing
npx claude-flow@alpha swarm "create unit tests for all service classes"
For larger projects requiring coordination:
# Initialize project swarm
npx claude-flow@alpha hive-mind spawn "e-commerce platform" \
--agents architect,backend-dev,frontend-dev,tester \
--topology hierarchical
# Continue development in same session
npx claude-flow@alpha swarm "implement user authentication" --continue-session
# Add new features
npx claude-flow@alpha swarm "add payment processing integration"
# Monitor progress
npx claude-flow@alpha swarm status --watch
Structured development using Specification โ Pseudocode โ Architecture โ Refinement โ Code:
# Full SPARC pipeline
npx claude-flow@alpha sparc pipeline "user management system"
# Individual SPARC phases
npx claude-flow@alpha sparc spec "define requirements for authentication"
npx claude-flow@alpha sparc architecture "design microservices structure"
npx claude-flow@alpha sparc code "implement user service"
# Test-driven development
npx claude-flow@alpha sparc tdd "payment processing module"
# Comprehensive code review
npx claude-flow@alpha swarm "perform security audit and code review" \
--agents security-analyst,reviewer,code-quality-checker
# Performance optimization
npx claude-flow@alpha swarm "analyze and optimize application performance" \
--agents performance-analyst,optimizer
# CI/CD setup
npx claude-flow@alpha swarm "setup complete CI/CD pipeline" \
--agents devops-engineer,cicd-specialist
# Container deployment
npx claude-flow@alpha swarm "containerize application with Docker" \
--agents docker-specialist,devops-engineer
# Kubernetes deployment
npx claude-flow@alpha swarm "deploy to Kubernetes cluster" \
--agents k8s-specialist,devops-engineer
# Generate documentation
npx claude-flow@alpha swarm "create comprehensive project documentation" \
--agents technical-writer,api-docs-generator
# Code maintenance
npx claude-flow@alpha swarm "refactor legacy code and improve maintainability" \
--agents refactoring-specialist,code-quality-checker
# Create new directory
mkdir my-api-project
cd my-api-project
# Initialize Claude-Flow
npx claude-flow@alpha init --force
# Initialize npm project
npm init -y
# Use SPARC specification mode
npx claude-flow@alpha sparc spec "REST API for task management with CRUD operations, authentication, and data validation"
# Generate system architecture
npx claude-flow@alpha sparc architecture "Node.js Express API with PostgreSQL database, JWT authentication, and comprehensive error handling"
# Generate implementation
npx claude-flow@alpha sparc code "implement the complete task management API based on the architecture"
# Create comprehensive tests
npx claude-flow@alpha swarm "create unit tests, integration tests, and API endpoint tests" \
--agents tester,test-automation-specialist
# Add CI/CD and deployment
npx claude-flow@alpha swarm "setup GitHub Actions CI/CD and Docker deployment" \
--agents devops-engineer,cicd-specialist
# Initialize large project swarm
npx claude-flow@alpha hive-mind spawn "full-stack social media application" \
--agents architect,planner,backend-dev,frontend-dev,mobile-dev,tester,devops-engineer \
--topology hierarchical \
--max-agents 12
# Create comprehensive architecture
npx claude-flow@alpha swarm "design microservices architecture with event-driven communication" \
--agents system-architect,backend-architect,frontend-architect
# Develop backend services
npx claude-flow@alpha swarm "implement user service, post service, and notification service" \
--agents backend-dev,api-developer,database-specialist
# Create frontend applications
npx claude-flow@alpha swarm "build React web app and React Native mobile app" \
--agents frontend-dev,mobile-dev,ui-ux-specialist
# Comprehensive testing
npx claude-flow@alpha swarm "create automated test suites and perform security audit" \
--agents tester,security-analyst,qa-specialist
# Deploy and monitor
npx claude-flow@alpha swarm "deploy to cloud and setup monitoring" \
--agents devops-engineer,cloud-specialist,monitoring-specialist
# Start TDD cycle
npx claude-flow@alpha sparc tdd "user authentication with email verification" \
--test-framework jest \
--coverage 95
# Create test specifications
npx claude-flow@alpha swarm "write comprehensive test cases for authentication flow" \
--agents test-architect,tdd-specialist
# Implement just enough to pass tests
npx claude-flow@alpha sparc code "implement minimal authentication logic to pass tests"
# Improve implementation
npx claude-flow@alpha sparc refinement "optimize authentication performance and security"
# Create integration tests
npx claude-flow@alpha swarm "add integration tests for complete authentication flow" \
--agents integration-tester,api-tester
# Core settings
export CLAUDE_FLOW_DEBUG=true
export CLAUDE_FLOW_LOG_LEVEL=info
export CLAUDE_FLOW_DATA_DIR=./data
export CLAUDE_FLOW_MAX_AGENTS=50
# API configuration
export CLAUDE_API_KEY="your_claude_api_key"
export OPENAI_API_KEY="your_openai_api_key"
export ANTHROPIC_API_KEY="your_anthropic_api_key"
# Performance tuning
export CLAUDE_FLOW_MEMORY_LIMIT=1024
export CLAUDE_FLOW_TIMEOUT=300000
export CLAUDE_FLOW_CONCURRENT_TASKS=10
Create .claude-flow.json in your project root:
{
"orchestrator": {
"maxConcurrentAgents": 100,
"taskQueueSize": 1000,
"defaultTopology": "mesh",
"autoScaling": true,
"timeoutMs": 300000
},
"memory": {
"backend": "sqlite",
"cacheSizeMB": 512,
"compressionEnabled": true,
"retentionDays": 30,
"indexingEnabled": true
},
"providers": {
"anthropic": {
"apiKey": "${CLAUDE_API_KEY}",
"model": "claude-3-sonnet",
"temperature": 0.7,
"maxTokens": 4096
},
"openai": {
"apiKey": "${OPENAI_API_KEY}",
"model": "gpt-4",
"temperature": 0.7,
"maxTokens": 4096
}
},
"agents": {
"defaultAgent": "coder",
"agentProfiles": {
"development": ["coder", "reviewer", "tester"],
"architecture": ["architect", "planner", "system-designer"],
"devops": ["devops-engineer", "docker-specialist", "k8s-specialist"]
}
},
"swarm": {
"defaultTopology": "mesh",
"coordinationStrategy": "democratic",
"faultTolerance": true,
"loadBalancing": true
},
"hooks": {
"enabled": true,
"autoFormat": true,
"notifications": true,
"preTaskHooks": ["backup", "validation"],
"postTaskHooks": ["cleanup", "metrics"]
},
"security": {
"validateInputs": true,
"sanitizeOutputs": true,
"encryptMemory": true,
"auditLogging": true
},
"performance": {
"cacheEnabled": true,
"compressionEnabled": true,
"parallelExecution": true,
"resourceLimits": {
"maxMemoryMB": 2048,
"maxCpuPercent": 80
}
}
}
Define custom agent combinations for specific use cases:
{
"agentProfiles": {
"web-development": {
"agents": ["frontend-dev", "backend-dev", "fullstack-dev"],
"topology": "hierarchical",
"coordination": "leader-follower"
},
"data-science": {
"agents": ["ml-developer", "data-analyst", "python-specialist"],
"topology": "mesh",
"coordination": "collaborative"
},
"enterprise-security": {
"agents": ["security-analyst", "penetration-tester", "compliance-checker"],
"topology": "centralized",
"coordination": "expert-led"
}
}
}
{
"memory": {
"backends": {
"primary": {
"type": "sqlite",
"path": "./data/memory.db",
"compression": true
},
"cache": {
"type": "redis",
"host": "localhost",
"port": 6379,
"ttl": 3600
},
"backup": {
"type": "s3",
"bucket": "claude-flow-backup",
"region": "us-east-1"
}
},
"synchronization": {
"strategy": "eventual-consistency",
"conflictResolution": "last-write-wins",
"replicationFactor": 3
}
}
}
{
"performance": {
"optimization": {
"agentPooling": true,
"connectionReuse": true,
"batchProcessing": true,
"asyncExecution": true
},
"monitoring": {
"metricsEnabled": true,
"tracingEnabled": true,
"profilingEnabled": false,
"alerting": {
"cpu": 90,
"memory": 85,
"diskSpace": 80
}
},
"scaling": {
"autoScale": true,
"minAgents": 2,
"maxAgents": 50,
"scaleUpThreshold": 80,
"scaleDownThreshold": 30
}
}
}
# Start MCP server
npx claude-flow@alpha mcp start --port 3000
# Configure MCP tools
npx claude-flow@alpha mcp config --tools all
# Add custom MCP server
npx claude-flow@alpha mcp add-server \
--name "custom-tools" \
--command "node custom-mcp-server.js"
# Add Claude-Flow MCP server to Claude Code
claude mcp add claude-flow npx claude-flow@alpha mcp start
# List available MCP tools
npx claude-flow@alpha mcp tools --list
# Test MCP connection
npx claude-flow@alpha mcp test --tool swarm_init
Issue: npm install fails with permission errors
# Solution 1: Use npx instead
npx claude-flow@alpha --help
# Solution 2: Fix npm permissions
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
# Solution 3: Use node version manager
nvm install 20
nvm use 20
Issue: SQLite compilation fails
# Solution 1: Install build tools
# On Ubuntu/Debian:
sudo apt-get install build-essential python3
# On macOS:
xcode-select --install
# On Windows:
npm install --global windows-build-tools
# Solution 2: Use prebuilt binaries
npm install --no-optional
Issue: "Agent not found" error
# Check available agents
npx claude-flow@alpha agents list
# Verify agent spelling
npx claude-flow@alpha agents info coder
# Use default agent if uncertain
npx claude-flow@alpha swarm "your task" --agent coder
Issue: Memory-related errors
# Check memory usage
npx claude-flow@alpha memory stats
# Clear memory cache
npx claude-flow@alpha memory clear --cache
# Optimize memory settings
npx claude-flow@alpha config set memory.cacheSizeMB 256
Issue: API rate limiting
# Check API status
npx claude-flow@alpha health --api
# Configure rate limiting
npx claude-flow@alpha config set providers.anthropic.rateLimit 60
# Use multiple providers
npx claude-flow@alpha config set providers.fallback openai
Issue: Slow task execution
# Run diagnostics
npx claude-flow@alpha diagnostics --performance
# Optimize configuration
npx claude-flow@alpha optimize --auto
# Monitor real-time performance
npx claude-flow@alpha monitor --interval 5s
Issue: High memory usage
# Check memory breakdown
npx claude-flow@alpha memory analyze
# Enable compression
npx claude-flow@alpha config set memory.compressionEnabled true
# Reduce cache size
npx claude-flow@alpha config set memory.cacheSizeMB 128
Enable detailed logging for troubleshooting:
# Enable debug mode
export CLAUDE_FLOW_DEBUG=true
export CLAUDE_FLOW_LOG_LEVEL=debug
# Run with verbose output
npx claude-flow@alpha swarm "your task" --verbose
# Generate diagnostic report
npx claude-flow@alpha diagnostics --full --output debug-report.json
# View recent logs
npx claude-flow@alpha logs --tail 100
# Filter logs by level
npx claude-flow@alpha logs --level error
# Search logs
npx claude-flow@alpha logs --grep "swarm"
# Export logs
npx claude-flow@alpha logs --export logs.json
# Comprehensive health check
npx claude-flow@alpha health --comprehensive
# Check specific components
npx claude-flow@alpha health --component memory
npx claude-flow@alpha health --component agents
npx claude-flow@alpha health --component mcp
# Automated health monitoring
npx claude-flow@alpha health --monitor --interval 60s
| Component | Minimum | Recommended | Optimal |
|---|---|---|---|
| CPU | 2 cores | 4 cores | 8+ cores |
| RAM | 4 GB | 8 GB | 16+ GB |
| Storage | 1 GB free | 5 GB free | 20+ GB SSD |
| Network | 1 Mbps | 10 Mbps | 100+ Mbps |
# Configure memory limits
npx claude-flow@alpha config set memory.cacheSizeMB 512
npx claude-flow@alpha config set memory.maxMemoryMB 2048
# Enable compression
npx claude-flow@alpha config set memory.compressionEnabled true
npx claude-flow@alpha config set memory.indexingEnabled true
# Set retention policies
npx claude-flow@alpha config set memory.retentionDays 30
npx claude-flow@alpha config set memory.autoCleanup true
# Configure agent pools
npx claude-flow@alpha config set orchestrator.maxConcurrentAgents 50
npx claude-flow@alpha config set orchestrator.agentPoolSize 20
# Enable auto-scaling
npx claude-flow@alpha config set swarm.autoScaling true
npx claude-flow@alpha config set swarm.minAgents 2
npx claude-flow@alpha config set swarm.maxAgents 100
# Process multiple tasks in parallel
npx claude-flow@alpha swarm batch \
"create user service" \
"create product service" \
"create order service" \
--parallel
# Use agent profiles for efficiency
npx claude-flow@alpha swarm "build microservices" \
--profile backend-development \
--optimize-for speed
# Enable aggressive caching
npx claude-flow@alpha config set performance.cacheEnabled true
npx claude-flow@alpha config set performance.cacheStrategy aggressive
# Pre-warm caches
npx claude-flow@alpha cache warm --agents common
npx claude-flow@alpha cache warm --tools frequent
# Configure connection pooling
npx claude-flow@alpha config set network.connectionPooling true
npx claude-flow@alpha config set network.maxConnections 100
# Enable compression
npx claude-flow@alpha config set network.compressionEnabled true
npx claude-flow@alpha config set network.timeout 30000
# Real-time performance monitoring
npx claude-flow@alpha monitor --dashboard
# Generate performance report
npx claude-flow@alpha performance report --period 7d
# Set up performance alerts
npx claude-flow@alpha alerts configure \
--cpu-threshold 80 \
--memory-threshold 85 \
--response-time-threshold 5000
# Initialize GitHub integration
npx claude-flow@alpha github init --token YOUR_GITHUB_TOKEN
# Configure repository
npx claude-flow@alpha github config \
--repo "username/repository" \
--default-branch main
# Pull Request Management
npx claude-flow@alpha github pr-manager \
"review and merge pending PRs" \
--auto-merge \
--require-reviews 2
# Issue Management
npx claude-flow@alpha github issue-tracker \
"analyze and categorize open issues" \
--auto-label \
--assign-to-team
# Release Management
npx claude-flow@alpha github release-manager \
"prepare v2.1.0 release" \
--generate-changelog \
--create-release-notes
# Automated code review
npx claude-flow@alpha github code-review \
--pr-number 123 \
--agents security-analyst,code-reviewer \
--auto-comment
# Repository analysis
npx claude-flow@alpha github analyze-repo \
--metrics code-quality,security,performance \
--generate-report
# Containerize application
npx claude-flow@alpha docker containerize \
--app-type node \
--multi-stage \
--optimize-size
# Build and push images
npx claude-flow@alpha docker build-push \
--registry docker.io \
--tags latest,v2.0.0
# Container orchestration
npx claude-flow@alpha docker compose \
--services api,database,redis \
--environment production
# Deploy to Kubernetes
npx claude-flow@alpha k8s deploy \
--cluster production \
--namespace default \
--replicas 3
# Manage services
npx claude-flow@alpha k8s services \
"setup load balancer and ingress" \
--ssl-enabled \
--auto-scaling
# Monitor cluster
npx claude-flow@alpha k8s monitor \
--real-time \
--alerts \
--dashboard
# Setup CI/CD pipeline
npx claude-flow@alpha cicd github-actions \
"create complete CI/CD workflow" \
--tests \
--security-scan \
--deploy-staging
# Custom workflows
npx claude-flow@alpha cicd custom \
--provider github-actions \
--stages "lint,test,build,deploy" \
--environments "staging,production"
# Jenkins pipeline
npx claude-flow@alpha cicd jenkins \
"setup Jenkins pipeline with parallel stages" \
--agents 4 \
--parallel-tests
# Deploy to AWS
npx claude-flow@alpha aws deploy \
--service ecs \
--region us-east-1 \
--auto-scaling
# Infrastructure as Code
npx claude-flow@alpha aws infrastructure \
"create complete AWS infrastructure" \
--terraform \
--best-practices
# Azure deployment
npx claude-flow@alpha azure deploy \
--service app-service \
--resource-group production \
--scaling-rules
# GCP deployment
npx claude-flow@alpha gcp deploy \
--service cloud-run \
--region us-central1 \
--auto-scaling
Q: What is Claude-Flow? A: Claude-Flow is an enterprise-grade AI agent orchestration platform that enables distributed AI development through swarm intelligence, featuring 54+ specialized agents and 87 MCP tools.
Q: How is Claude-Flow different from other AI tools? A: Claude-Flow provides true multi-agent coordination with swarm intelligence, persistent memory management, and enterprise-grade features like security, monitoring, and scalability.
Q: Do I need Claude Code to use Claude-Flow? A: While Claude-Flow can work independently, Claude Code integration provides the best experience with full MCP protocol support and seamless agent coordination.
Q: Which Node.js version should I use? A: Claude-Flow requires Node.js โฅ 20.0.0. We recommend using the latest LTS version for best performance and security.
Q: Can I use Claude-Flow without global installation?
A: Yes! Using npx claude-flow@alpha is actually recommended as it always uses the latest version without requiring global installation.
Q: How do I handle API key configuration?
A: Set your API keys as environment variables or in the .claude-flow.json configuration file. Never commit API keys to version control.
Q: How many agents can I run simultaneously? A: By default, Claude-Flow can handle up to 100 concurrent agents. This can be configured based on your system resources and API limits.
Q: Can I create custom agents? A: Currently, Claude-Flow provides 54+ pre-built agents. Custom agent creation is planned for a future release.
Q: How does the memory system work? A: Claude-Flow uses a distributed memory system with SQLite backend by default. Memory is automatically synchronized across agents and persists between sessions.
Q: What swarm topology should I choose? A:
Q: How can I improve task execution speed? A: Enable parallel processing, use appropriate swarm topologies, configure caching, and ensure adequate system resources.
Q: What should I do if I hit API rate limits? A: Configure multiple providers, adjust rate limiting settings, or implement request batching and queuing.
Q: How much disk space does Claude-Flow use? A: Base installation requires ~100MB. Memory database and cache can grow based on usage, typically 10-100MB for most projects.
Q: Can Claude-Flow work with my existing CI/CD pipeline? A: Yes, Claude-Flow provides integrations for GitHub Actions, Jenkins, and other CI/CD platforms.
Q: Is Claude-Flow compatible with Docker and Kubernetes? A: Absolutely! Claude-Flow includes specialized agents for Docker containerization and Kubernetes orchestration.
Q: Can I use Claude-Flow in enterprise environments? A: Yes, Claude-Flow is designed for enterprise use with security features, audit logging, and scalable architecture.
Q: What should I do if an agent fails?
A: Claude-Flow includes automatic fault recovery. You can also check logs with npx claude-flow@alpha logs and restart failed tasks.
Q: How do I debug performance issues?
A: Use the built-in diagnostics: npx claude-flow@alpha diagnostics --performance and monitor real-time metrics.
Q: Where can I get help if I'm stuck? A: Check this guide, review the comprehensive documentation, search GitHub issues, or join our Discord community.
Q: How does SPARC methodology work? A: SPARC (Specification โ Pseudocode โ Architecture โ Refinement โ Code) is a structured development methodology that ensures thorough planning and high-quality implementation.
Q: Can I use Claude-Flow for machine learning projects? A: Yes! Claude-Flow includes specialized ML agents for model development, training, and deployment.
Q: How secure is Claude-Flow? A: Claude-Flow includes enterprise-grade security features including input validation, data encryption, audit logging, and role-based access control.
We welcome contributions! Please see our Contributing Guide for details on:
You now have everything you need to master Claude-Flow!
๐ Start Building | ๐ API Reference | ๐๏ธ Architecture Guide
Claude-Flow User Guide v2.0.0
Built with โค๏ธ by the Claude-Flow Community
</div>