v2/docs/SWARM_INITIALIZATION_GUIDE.md
Date: 2025-10-25 Claude-Flow Version: 2.7.14
# THIS DOES NOT EXIST:
npx claude-flow@alpha hooks swarm-init --topology adaptive --max-agents 6
# Error: ❌ Unknown hooks command: swarm-init
Why? Hooks are for lifecycle events (pre-task, post-task, etc.), NOT swarm initialization.
For ruv-swarm (WASM-powered):
// Call this from within Claude Code:
mcp__ruv-swarm__swarm_init({
topology: "mesh", // mesh, hierarchical, ring, star
maxAgents: 6,
strategy: "adaptive" // balanced, specialized, adaptive
})
For claude-flow MCP:
// Call this from within Claude Code:
mcp__claude-flow__swarm_init({
topology: "hierarchical",
maxAgents: 8,
strategy: "balanced"
})
Example Result:
{
"id": "swarm-1761410358918",
"message": "Successfully initialized mesh swarm with 6 max agents",
"topology": "mesh",
"strategy": "adaptive",
"maxAgents": 6,
"features": {
"cognitive_diversity": true,
"neural_networks": true,
"forecasting": false,
"simd_support": true
},
"performance": {
"initialization_time_ms": 1.28,
"memory_usage_mb": 48
}
}
For task-based swarm deployment:
# Requires Claude Code CLI
npx claude-flow@alpha swarm "Build a REST API with authentication" --max-agents 6
# With options:
npx claude-flow@alpha swarm "Analyze codebase" \
--max-agents 6 \
--strategy research \
--mode mesh \
--read-only
CLI Options:
--strategy - research, development, analysis, testing, optimization--mode - centralized, distributed, hierarchical, mesh, hybrid--max-agents - Maximum number of agents (default: 5)--parallel - Enable parallel execution (2.8-4.4x speedup)--monitor - Real-time swarm monitoring--background - Run in background--claude - Open Claude Code CLI--executor - Use built-in executor--read-only - Analysis mode (no code changes)Interactive wizard:
npx claude-flow@alpha hive-mind wizard
Direct spawn:
npx claude-flow@alpha hive-mind spawn "Build REST API with auth"
npx claude-flow@alpha hive-mind spawn "Analyze security" --claude
Check status:
npx claude-flow@alpha hive-mind status
npx claude-flow@alpha hive-mind metrics
Hooks are for lifecycle management, NOT swarm creation:
# Before task starts
npx claude-flow@alpha hooks pre-task \
--description "Build API" \
--task-id "task-123"
# After task completes
npx claude-flow@alpha hooks post-task \
--task-id "task-123" \
--analyze-performance
# Before file edit
npx claude-flow@alpha hooks pre-edit \
--file "src/api.js" \
--operation edit
# After file edit
npx claude-flow@alpha hooks post-edit \
--file "src/api.js" \
--memory-key "swarm/123/edits/api"
# End of session
npx claude-flow@alpha hooks session-end \
--export-metrics \
--generate-summary
For cloud-based swarm orchestration:
// 1. Register/Login
mcp__flow-nexus__user_register({ email, password })
mcp__flow-nexus__user_login({ email, password })
// 2. Initialize cloud swarm
mcp__flow-nexus__swarm_init({
topology: "hierarchical",
maxAgents: 8,
strategy: "balanced"
})
// 3. Spawn cloud agents
mcp__flow-nexus__agent_spawn({
type: "researcher",
name: "researcher-1",
capabilities: ["web-search", "data-analysis"]
})
// 4. Orchestrate tasks
mcp__flow-nexus__task_orchestrate({
task: "Build microservices architecture",
strategy: "parallel",
priority: "high"
})
| Method | Speed | Control | Complexity | Best For |
|---|---|---|---|---|
| MCP Tools | Fast (1-2ms) | High | Low | Claude Code integration |
| CLI Swarm | Medium | Medium | Medium | Terminal workflows |
| Hive Mind | Slower | High | High | Complex orchestration |
| Flow-Nexus | Variable | Highest | High | Cloud deployment |
npx claude-flow@alpha swarm "Research GraphQL best practices" \
--strategy research \
--max-agents 3 \
--read-only
npx claude-flow@alpha swarm "Build authentication service" \
--strategy development \
--max-agents 5 \
--parallel \
--monitor
// In Claude Code:
mcp__ruv-swarm__swarm_init({
topology: "mesh",
maxAgents: 4,
strategy: "adaptive"
})
mcp__ruv-swarm__agent_spawn({
type: "coder",
name: "backend-dev"
})
mcp__ruv-swarm__task_orchestrate({
task: "Implement user authentication",
strategy: "sequential",
priority: "high"
})
npx claude-flow@alpha hive-mind spawn \
"Build e-commerce platform" \
--claude
Solution: Use npx claude-flow@alpha swarm or MCP tools instead
Solution: Either:
--executor flag for built-in executionCheck:
claude mcp listnpm install.swarm/memory.dbDocumentation:
/README.md/docs/TOOL_VALIDATION_REPORT.md/docs/AGENTIC_FLOW_INTEGRATION_REVIEW.mdSkills:
.claude/skills/swarm-orchestration/SKILL.md.claude/skills/hive-mind-advanced/SKILL.mdOfficial Guides:
Created: 2025-10-25 Updated: 2025-10-25 Author: Claude Code (Claude Sonnet 4.5)