**When starting work on complex tasks, Claude Code MUST automatically:**
Sign in to like and favorite skills
When starting work on complex tasks, Claude Code MUST automatically:
When user says "spawn swarm" or requests complex work, Claude Code MUST in ONE message:
MCP alone does NOT execute work - Task tool agents do the actual work!
The routing system has 3 tiers for optimal cost/performance:
| Tier | Handler | Latency | Cost | Use Cases |
|---|---|---|---|---|
| 1 | Agent Booster (WASM) | <1ms | $0 | Simple transforms (var→const, add types, etc.) - Skip LLM entirely |
| 2 | Haiku | ~500ms | $0.0002 | Simple tasks, low complexity (<30%) |
| 3 | Sonnet/Opus | 2-5s | $0.003-0.015 | Complex reasoning, architecture, security (>30%) |
When you see these recommendations:
[AGENT_BOOSTER_AVAILABLE]var-to-constadd-typesadd-error-handlingasync-awaitadd-loggingremove-console[TASK_MODEL_RECOMMENDATION] Use model="X"// If hook recommends: [TASK_MODEL_RECOMMENDATION] Use model="opus" Task({ prompt: "...", subagent_type: "coder", model: "opus" // ← USE THE RECOMMENDED MODEL })
Model Selection Logic:
| Complexity | Model | Use For |
|---|---|---|
| Agent Booster intent detected | Skip LLM | var→const, add-types, remove-console (352x faster) |
| High (architecture, system design, security) | opus | Complex reasoning, multi-step planning |
| Medium (features, refactoring, debugging) | sonnet | Balanced capability and speed |
| Low (formatting, simple fixes, docs) | haiku | Fast, cost-effective tasks |
CRITICAL: Always check for
[AGENT_BOOSTER_AVAILABLE][TASK_MODEL_RECOMMENDATION]To prevent goal drift, context drift, and agent desynchronization, ALWAYS use this configuration for coding swarms:
mcp__ruv-swarm__swarm_init({ topology: "hierarchical", // Single coordinator enforces alignment maxAgents: 8, // Smaller team = less drift surface strategy: "specialized" // Clear roles reduce ambiguity })
Why This Prevents Drift:
| Choice | Anti-Drift Benefit |
|---|---|
| hierarchical | Coordinator validates each output against goal, catches divergence early |
| maxAgents: 6-8 | Fewer agents = less coordination overhead, easier alignment |
| specialized | Clear boundaries - each agent knows exactly what to do, no overlap |
Consensus for Hive-Mind: Use
raftAdditional Anti-Drift Measures:
post-taskWhen the user requests a complex task (multi-file changes, feature implementation, refactoring), immediately execute this pattern in a SINGLE message:
// STEP 1: Initialize swarm coordination via MCP (in parallel with agent spawning) // USE ANTI-DRIFT CONFIG: hierarchical + specialized + small team mcp__ruv-swarm__swarm_init({ topology: "hierarchical", maxAgents: 8, strategy: "specialized" }) // STEP 2: Spawn agents concurrently using Claude Code's Task tool // ALL Task calls MUST be in the SAME message for parallel execution Task("Coordinator", "You are the swarm coordinator. Initialize session, coordinate other agents via memory. Run: npx claude-flow@v3alpha hooks session-start", "hierarchical-coordinator") Task("Researcher", "Analyze requirements and existing code patterns. Store findings in memory via hooks.", "researcher") Task("Architect", "Design implementation approach based on research. Document decisions in memory.", "system-architect") Task("Coder", "Implement the solution following architect's design. Coordinate via hooks.", "coder") Task("Tester", "Write tests for the implementation. Report coverage via hooks.", "tester") Task("Reviewer", "Review code quality and security. Document findings.", "reviewer") // STEP 3: Batch all todos TodoWrite({ todos: [ {content: "Initialize swarm coordination", status: "in_progress", activeForm: "Initializing swarm"}, {content: "Research and analyze requirements", status: "in_progress", activeForm: "Researching requirements"}, {content: "Design architecture", status: "pending", activeForm: "Designing architecture"}, {content: "Implement solution", status: "pending", activeForm: "Implementing solution"}, {content: "Write tests", status: "pending", activeForm: "Writing tests"}, {content: "Review and finalize", status: "pending", activeForm: "Reviewing code"} ]}) // STEP 4: Store swarm state in memory mcp__claude-flow__memory_usage({ action: "store", namespace: "swarm", key: "current-session", value: JSON.stringify({task: "[user's task]", agents: 6, startedAt: new Date().toISOString()}) })
| Code | Task | Agents |
|---|---|---|
| 1 | Bug Fix | coordinator, researcher, coder, tester |
| 3 | Feature | coordinator, architect, coder, tester, reviewer |
| 5 | Refactor | coordinator, architect, coder, reviewer |
| 7 | Performance | coordinator, perf-engineer, coder |
| 9 | Security | coordinator, security-architect, auditor |
| 11 | Memory | coordinator, memory-specialist, perf-engineer |
| 13 | Docs | researcher, api-docs |
Codes 1-11: hierarchical/specialized (anti-drift). Code 13: mesh/balanced
AUTO-INVOKE SWARM when task involves:
SKIP SWARM for:
ABSOLUTE RULES:
MANDATORY PATTERNS:
NEVER save to root folder. Use these directories:
/src/tests/docs/config/scripts/examplesThis project is configured with Claude Flow V3 (Anti-Drift Defaults):
| Command | Subcommands | Description |
|---|---|---|
| 4 | Project initialization with wizard, presets, skills, hooks |
| 8 | Agent lifecycle (spawn, list, status, stop, metrics, pool, health, logs) |
| 6 | Multi-agent swarm coordination and orchestration |
| 11 | AgentDB memory with vector search (150x-12,500x faster) |
| 9 | MCP server management and tool execution |
| 6 | Task creation, assignment, and lifecycle |
| 7 | Session state management and persistence |
| 7 | Configuration management and provider setup |
| 3 | System status monitoring with watch mode |
| 3 | Service startup and quick launch |
| 6 | Workflow execution and template management |
| 17 | Self-learning hooks + 12 background workers |
| 6 | Queen-led Byzantine fault-tolerant consensus |
| Command | Subcommands | Description |
|---|---|---|
| 5 | Background worker daemon (start, stop, status, trigger, enable) |
| 5 | Neural pattern training (train, status, patterns, predict, optimize) |
| 6 | Security scanning (scan, audit, cve, threats, validate, report) |
| 5 | Performance profiling (benchmark, profile, metrics, optimize, report) |
| 5 | AI providers (list, add, remove, test, configure) |
| 5 | Plugin management (list, install, uninstall, enable, disable) |
| 5 | Deployment management (deploy, rollback, status, environments, release) |
| 4 | Vector embeddings (embed, batch, search, init) - 75x faster with agentic-flow |
| 4 | Claims-based authorization (check, grant, revoke, list) |
| 5 | V2 to V3 migration with rollback support |
| 4 | Background process management |
| 1 | System diagnostics with health checks |
| 4 | Shell completions (bash, zsh, fish, powershell) |
# Initialize project npx claude-flow@v3alpha init --wizard # Start daemon with background workers npx claude-flow@v3alpha daemon start # Spawn an agent npx claude-flow@v3alpha agent spawn -t coder --name my-coder # Initialize swarm npx claude-flow@v3alpha swarm init --v3-mode # Search memory (HNSW-indexed) npx claude-flow@v3alpha memory search -q "authentication patterns" # System diagnostics npx claude-flow@v3alpha doctor --fix # Security scan npx claude-flow@v3alpha security scan --depth full # Performance benchmark npx claude-flow@v3alpha performance benchmark --suite all
coderreviewertesterplannerresearchersecurity-architectsecurity-auditormemory-specialistperformance-engineerCVE remediation, input validation, path security:
InputValidatorPathValidatorSafeExecutorPasswordHasherTokenGeneratorIntegrates agentic-flow optimizations for 30-50% token reduction:
import { getTokenOptimizer } from '@claude-flow/integration'; const optimizer = await getTokenOptimizer(); // Compact context (32% fewer tokens) const ctx = await optimizer.getCompactContext("auth patterns"); // 352x faster edits = fewer retries await optimizer.optimizedEdit(file, old, new, "typescript"); // Optimal config (100% success rate) const config = optimizer.getOptimalConfig(agentCount);
| Feature | Token Savings |
|---|---|
| ReasoningBank retrieval | -32% |
| Agent Booster edits | -15% |
| Cache (95% hit rate) | -10% |
| Optimal batch size | -20% |
hierarchical-coordinatormesh-coordinatoradaptive-coordinatorcollective-intelligence-coordinatorswarm-memory-managerbyzantine-coordinatorraft-managergossip-coordinatorconsensus-buildercrdt-synchronizerquorum-managersecurity-managerperf-analyzerperformance-benchmarkertask-orchestratormemory-coordinatorsmart-agentgithub-modespr-managercode-review-swarmissue-trackerrelease-managerworkflow-automationproject-board-syncrepo-architectmulti-repo-swarmsparc-coordsparc-coderspecificationpseudocodearchitecturerefinementbackend-devmobile-devml-developercicd-engineerapi-docssystem-architectcode-analyzerbase-template-generatortdd-london-swarmproduction-validator| Category | Hooks | Purpose |
|---|---|---|
| Core | | Tool lifecycle |
| Session | | Context management |
| Intelligence | | Neural learning |
| Learning | | Reinforcement |
| Worker | Priority | Description |
|---|---|---|
| normal | Deep knowledge acquisition |
| high | Performance optimization |
| low | Memory consolidation |
| normal | Predictive preloading |
| critical | Security analysis |
| normal | Codebase mapping |
| low | Resource preloading |
| normal | Deep code analysis |
| normal | Auto-documentation |
| normal | Refactoring suggestions |
| normal | Performance benchmarking |
| normal | Test coverage analysis |
# Core hooks npx claude-flow@v3alpha hooks pre-task --description "[task]" npx claude-flow@v3alpha hooks post-task --task-id "[id]" --success true npx claude-flow@v3alpha hooks post-edit --file "[file]" --train-patterns # Session management npx claude-flow@v3alpha hooks session-start --session-id "[id]" npx claude-flow@v3alpha hooks session-end --export-metrics true npx claude-flow@v3alpha hooks session-restore --session-id "[id]" # Intelligence routing npx claude-flow@v3alpha hooks route --task "[task]" npx claude-flow@v3alpha hooks explain --topic "[topic]" # Neural learning npx claude-flow@v3alpha hooks pretrain --model-type moe --epochs 10 npx claude-flow@v3alpha hooks build-agents --agent-types coder,tester # Background workers npx claude-flow@v3alpha hooks worker list npx claude-flow@v3alpha hooks worker dispatch --trigger audit npx claude-flow@v3alpha hooks worker status
V3 includes the RuVector Intelligence System:
The 4-step intelligence pipeline:
Features:
hierarchicalmeshhierarchical-meshadaptivebyzantineraftgossipcrdtquorum| Metric | Target | Status |
|---|---|---|
| HNSW Search | 150x-12,500x faster | Implemented (persistent) |
| Memory Reduction | 50-75% with quantization | Implemented (3.92x Int8) |
| SONA Integration | Pattern learning | Implemented (ReasoningBank) |
| Flash Attention | 2.49x-7.47x speedup | In progress |
| MCP Response | <100ms | Achieved |
| CLI Startup | <500ms | Achieved |
| SONA Adaptation | <0.05ms | In progress |
# Configuration CLAUDE_FLOW_CONFIG=./claude-flow.config.json CLAUDE_FLOW_LOG_LEVEL=info # Provider API Keys ANTHROPIC_API_KEY=sk-ant-... OPENAI_API_KEY=sk-... GOOGLE_API_KEY=... # MCP Server CLAUDE_FLOW_MCP_PORT=3000 CLAUDE_FLOW_MCP_HOST=localhost CLAUDE_FLOW_MCP_TRANSPORT=stdio # Memory CLAUDE_FLOW_MEMORY_BACKEND=hybrid CLAUDE_FLOW_MEMORY_PATH=./data/memory
Run
npx claude-flow@v3alpha doctor# Add MCP servers claude mcp add claude-flow npx claude-flow@v3alpha mcp start claude mcp add ruv-swarm npx ruv-swarm mcp start # Optional claude mcp add flow-nexus npx flow-nexus@latest mcp start # Optional # Start daemon npx claude-flow@v3alpha daemon start # Run doctor npx claude-flow@v3alpha doctor --fix
KEY: MCP coordinates the strategy, Claude Code's Task tool executes with real agents.
When publishing CLI changes, you MUST:
@claude-flow/cliclaude-flow# STEP 1: Build and publish CLI cd v3/@claude-flow/cli npm version 3.0.0-alpha.XXX --no-git-tag-version npm run build npm publish --tag alpha npm dist-tag add @claude-flow/[email protected] latest # STEP 2: Publish umbrella cd /workspaces/claude-flow npm version 3.0.0-alpha.YYY --no-git-tag-version npm publish --tag v3alpha # STEP 3: Update ALL umbrella tags (CRITICAL - DON'T SKIP!) npm dist-tag add [email protected] latest npm dist-tag add [email protected] alpha
Verification (MUST DO before telling user):
npm view @claude-flow/cli dist-tags --json npm view claude-flow dist-tags --json # BOTH packages need: alpha AND latest pointing to newest version
| Package | Tag | Command Users Run |
|---|---|---|
| | |
| | |
| | |
| | |
| | |
The umbrella
tag is MOST commonly forgotten - users run alpha
!npx claude-flow@alpha
Remember: Claude Flow coordinates, Claude Code creates!
Do what has been asked; nothing more, nothing less. NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one. NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User. Never save working files, text/mds and tests to the root folder. After spawning a swarm, wait, don't continuously check status.