CLAUDE.md

1# Claude Code Configuration - Claude Flow V3
2 
3## 🚨 AUTOMATIC SWARM ORCHESTRATION
4 
5**When starting work on complex tasks, Claude Code MUST automatically:**
6 
71. **Initialize the swarm** using CLI tools via Bash
82. **Spawn concurrent agents** using Claude Code's Task tool
93. **Coordinate via hooks** and memory
10 
11### 🚨 CRITICAL: CLI + Task Tool in SAME Message
12 
13**When user says "spawn swarm" or requests complex work, Claude Code MUST in ONE message:**
141. Call CLI tools via Bash to initialize coordination
152. **IMMEDIATELY** call Task tool to spawn REAL working agents
163. Both CLI and Task calls must be in the SAME response
17 
18**CLI coordinates, Task tool agents do the actual work!**
19 
20### 🤖 INTELLIGENT 3-TIER MODEL ROUTING (ADR-026)
21 
22**The routing system has 3 tiers for optimal cost/performance:**
23 
24| Tier | Handler | Latency | Cost | Use Cases |
25|------|---------|---------|------|-----------|
26| **1** | Agent Booster | <1ms | $0 | Simple transforms (var→const, add-types, remove-console) |
27| **2** | Haiku | ~500ms | $0.0002 | Simple tasks, bug fixes, low complexity |
28| **3** | Sonnet/Opus | 2-5s | $0.003-$0.015 | Architecture, security, complex reasoning |
29 
30**Before spawning agents, get routing recommendation:**
31```bash
32npx @claude-flow/cli@latest hooks pre-task --description &quot;[task description]&quot;
33```
34 
35**When you see these recommendations:**
36 
371. `[AGENT_BOOSTER_AVAILABLE]` → Skip LLM entirely, use Edit tool directly
38   - Intent types: `var-to-const`, `add-types`, `add-error-handling`, `async-await`, `add-logging`, `remove-console`
39 
402. `[TASK_MODEL_RECOMMENDATION] Use model="X"` → Use that model in Task tool:
41```javascript
42Task({
43  prompt: "...",
44  subagent_type: "coder",
45  model: "haiku"  // ← USE THE RECOMMENDED MODEL (haiku/sonnet/opus)
46})
47```
48 
49**Benefits:** 75% cost reduction, 352x faster for Tier 1 tasks
50 
51---
52 
53### 🛡️ Anti-Drift Config (PREFERRED)
54 
55**Use this to prevent agent drift:**
56```bash
57# Small teams (6-8 agents) - use hierarchical for tight control
58npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized
59 
60# Large teams (10-15 agents) - use hierarchical-mesh for V3 queen + peer communication
61npx @claude-flow/cli@latest swarm init --topology hierarchical-mesh --max-agents 15 --strategy specialized
62```
63 
64**Valid Topologies:**
65- `hierarchical` - Queen controls workers directly (anti-drift for small teams)
66- `hierarchical-mesh` - V3 queen + peer communication (recommended for 10+ agents)
67- `mesh` - Fully connected peer network
68- `ring` - Circular communication pattern
69- `star` - Central coordinator with spokes
70- `hybrid` - Dynamic topology switching
71 
72**Anti-Drift Guidelines:**
73- **hierarchical**: Coordinator catches divergence
74- **max-agents 6-8**: Smaller team = less drift
75- **specialized**: Clear roles, no overlap
76- **consensus**: raft (leader maintains state)
77 
78---
79 
80### 🔄 Auto-Start Swarm Protocol (Background Execution)
81 
82When the user requests a complex task, **spawn agents in background and WAIT for completion:**
83 
84```javascript
85// STEP 1: Initialize swarm coordination (anti-drift config)
86Bash("npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized")
87 
88// STEP 2: Spawn ALL agents IN BACKGROUND in a SINGLE message
89// Use run_in_background: true so agents work concurrently
90Task({
91  prompt: "Research requirements, analyze codebase patterns, store findings in memory",
92  subagent_type: "researcher",
93  description: "Research phase",
94  run_in_background: true  // ← CRITICAL: Run in background
95})
96Task({
97  prompt: "Design architecture based on research. Document decisions.",
98  subagent_type: "system-architect",
99  description: "Architecture phase",
100  run_in_background: true
101})
102Task({
103  prompt: "Implement the solution following the design. Write clean code.",
104  subagent_type: "coder",
105  description: "Implementation phase",
106  run_in_background: true
107})
108Task({
109  prompt: "Write comprehensive tests for the implementation.",
110  subagent_type: "tester",
111  description: "Testing phase",
112  run_in_background: true
113})
114Task({
115  prompt: "Review code quality, security, and best practices.",
116  subagent_type: "reviewer",
117  description: "Review phase",
118  run_in_background: true
119})
120 
121// STEP 3: WAIT - Tell user agents are working, then STOP
122// Say: "I've spawned 5 agents to work on this in parallel. They'll report back when done."
123// DO NOT check status repeatedly. Just wait for user or agent responses.
124```
125 
126### ⏸️ CRITICAL: Spawn and Wait Pattern
127 
128**After spawning background agents:**
129 
1301. **TELL USER** - "I've spawned X agents working in parallel on: [list tasks]"
1312. **STOP** - Do not continue with more tool calls
1323. **WAIT** - Let the background agents complete their work
1334. **RESPOND** - When agents return results, review and synthesize
134 
135**Example response after spawning:**
136```
137I've launched 5 concurrent agents to work on this:
138- 🔍 Researcher: Analyzing requirements and codebase
139- 🏗️ Architect: Designing the implementation approach
140- 💻 Coder: Implementing the solution
141- 🧪 Tester: Writing tests
142- 👀 Reviewer: Code review and security check
143 
144They're working in parallel. I'll synthesize their results when they complete.
145```
146 
147### 🚫 DO NOT:
148- Continuously check swarm status
149- Poll TaskOutput repeatedly
150- Add more tool calls after spawning
151- Ask "should I check on the agents?"
152 
153### ✅ DO:
154- Spawn all agents in ONE message
155- Tell user what's happening
156- Wait for agent results to arrive
157- Synthesize results when they return
158 
159## 🧠 AUTO-LEARNING PROTOCOL
160 
161### Before Starting Any Task
162```bash
163# 1. Search memory for relevant patterns from past successes
164Bash(&quot;npx @claude-flow/cli@latest memory search --query '[task keywords]' --namespace patterns&quot;)
165 
166# 2. Check if similar task was done before
167Bash(&quot;npx @claude-flow/cli@latest memory search --query '[task type]' --namespace tasks&quot;)
168 
169# 3. Load learned optimizations
170Bash(&quot;npx @claude-flow/cli@latest hooks route --task '[task description]'&quot;)
171```
172 
173### After Completing Any Task Successfully
174```bash
175# 1. Store successful pattern for future reference
176Bash(&quot;npx @claude-flow/cli@latest memory store --namespace patterns --key '[pattern-name]' --value '[what worked]'&quot;)
177 
178# 2. Train neural patterns on the successful approach
179Bash(&quot;npx @claude-flow/cli@latest hooks post-edit --file '[main-file]' --train-neural true&quot;)
180 
181# 3. Record task completion with metrics
182Bash(&quot;npx @claude-flow/cli@latest hooks post-task --task-id '[id]' --success true --store-results true&quot;)
183 
184# 4. Trigger optimization worker if performance-related
185Bash(&quot;npx @claude-flow/cli@latest hooks worker dispatch --trigger optimize&quot;)
186```
187 
188### Continuous Improvement Triggers
189 
190| Trigger | Worker | When to Use |
191|---------|--------|-------------|
192| After major refactor | `optimize` | Performance optimization |
193| After adding features | `testgaps` | Find missing test coverage |
194| After security changes | `audit` | Security analysis |
195| After API changes | `document` | Update documentation |
196| Every 5+ file changes | `map` | Update codebase map |
197| Complex debugging | `deepdive` | Deep code analysis |
198 
199### Memory-Enhanced Development
200 
201**ALWAYS check memory before:**
202- Starting a new feature (search for similar implementations)
203- Debugging an issue (search for past solutions)
204- Refactoring code (search for learned patterns)
205- Performance work (search for optimization strategies)
206 
207**ALWAYS store in memory after:**
208- Solving a tricky bug (store the solution pattern)
209- Completing a feature (store the approach)
210- Finding a performance fix (store the optimization)
211- Discovering a security issue (store the vulnerability pattern)
212 
213### 📋 Agent Routing (Anti-Drift)
214 
215| Code | Task | Agents |
216|------|------|--------|
217| 1 | Bug Fix | coordinator, researcher, coder, tester |
218| 3 | Feature | coordinator, architect, coder, tester, reviewer |
219| 5 | Refactor | coordinator, architect, coder, reviewer |
220| 7 | Performance | coordinator, perf-engineer, coder |
221| 9 | Security | coordinator, security-architect, auditor |
222| 11 | Docs | researcher, api-docs |
223 
224**Codes 1-9: hierarchical/specialized (anti-drift). Code 11: mesh/balanced**
225 
226### 🎯 Task Complexity Detection
227 
228**AUTO-INVOKE SWARM when task involves:**
229- Multiple files (3+)
230- New feature implementation
231- Refactoring across modules
232- API changes with tests
233- Security-related changes
234- Performance optimization
235- Database schema changes
236 
237**SKIP SWARM for:**
238- Single file edits
239- Simple bug fixes (1-2 lines)
240- Documentation updates
241- Configuration changes
242- Quick questions/exploration
243 
244## 🚨 CRITICAL: CONCURRENT EXECUTION & FILE MANAGEMENT
245 
246**ABSOLUTE RULES**:
2471. ALL operations MUST be concurrent/parallel in a single message
2482. **NEVER save working files, text/mds and tests to the root folder**
2493. ALWAYS organize files in appropriate subdirectories
2504. **USE CLAUDE CODE'S TASK TOOL** for spawning agents concurrently, not just MCP
251 
252### ⚡ GOLDEN RULE: "1 MESSAGE = ALL RELATED OPERATIONS"
253 
254**MANDATORY PATTERNS:**
255- **TodoWrite**: ALWAYS batch ALL todos in ONE call (5-10+ todos minimum)
256- **Task tool (Claude Code)**: ALWAYS spawn ALL agents in ONE message with full instructions
257- **File operations**: ALWAYS batch ALL reads/writes/edits in ONE message
258- **Bash commands**: ALWAYS batch ALL terminal operations in ONE message
259- **Memory operations**: ALWAYS batch ALL memory store/retrieve in ONE message
260 
261### 📁 File Organization Rules
262 
263**NEVER save to root folder. Use these directories:**
264- `/src` - Source code files
265- `/tests` - Test files
266- `/docs` - Documentation and markdown files
267- `/config` - Configuration files
268- `/scripts` - Utility scripts
269- `/examples` - Example code
270 
271## Project Config (Anti-Drift Defaults)
272 
273- **Topology**: hierarchical (prevents drift)
274- **Max Agents**: 8 (smaller = less drift)
275- **Strategy**: specialized (clear roles)
276- **Consensus**: raft
277- **Memory**: hybrid
278- **HNSW**: Enabled
279- **Neural**: Enabled
280 
281## 🚀 V3 CLI Commands (26 Commands, 140+ Subcommands)
282 
283### Core Commands
284 
285| Command | Subcommands | Description |
286|---------|-------------|-------------|
287| `init` | 4 | Project initialization with wizard, presets, skills, hooks |
288| `agent` | 8 | Agent lifecycle (spawn, list, status, stop, metrics, pool, health, logs) |
289| `swarm` | 6 | Multi-agent swarm coordination and orchestration |
290| `memory` | 11 | AgentDB memory with vector search (150x-12,500x faster) |
291| `mcp` | 9 | MCP server management and tool execution |
292| `task` | 6 | Task creation, assignment, and lifecycle |
293| `session` | 7 | Session state management and persistence |
294| `config` | 7 | Configuration management and provider setup |
295| `status` | 3 | System status monitoring with watch mode |
296| `workflow` | 6 | Workflow execution and template management |
297| `hooks` | 17 | Self-learning hooks + 12 background workers |
298| `hive-mind` | 6 | Queen-led Byzantine fault-tolerant consensus |
299 
300### Advanced Commands
301 
302| Command | Subcommands | Description |
303|---------|-------------|-------------|
304| `daemon` | 5 | Background worker daemon (start, stop, status, trigger, enable) |
305| `neural` | 5 | Neural pattern training (train, status, patterns, predict, optimize) |
306| `security` | 6 | Security scanning (scan, audit, cve, threats, validate, report) |
307| `performance` | 5 | Performance profiling (benchmark, profile, metrics, optimize, report) |
308| `providers` | 5 | AI providers (list, add, remove, test, configure) |
309| `plugins` | 5 | Plugin management (list, install, uninstall, enable, disable) |
310| `deployment` | 5 | Deployment management (deploy, rollback, status, environments, release) |
311| `embeddings` | 4 | Vector embeddings (embed, batch, search, init) - 75x faster with agentic-flow |
312| `claims` | 4 | Claims-based authorization (check, grant, revoke, list) |
313| `migrate` | 5 | V2 to V3 migration with rollback support |
314| `doctor` | 1 | System diagnostics with health checks |
315| `completions` | 4 | Shell completions (bash, zsh, fish, powershell) |
316 
317### Quick CLI Examples
318 
319```bash
320# Initialize project
321npx @claude-flow/cli@latest init --wizard
322 
323# Start daemon with background workers
324npx @claude-flow/cli@latest daemon start
325 
326# Spawn an agent
327npx @claude-flow/cli@latest agent spawn -t coder --name my-coder
328 
329# Initialize swarm
330npx @claude-flow/cli@latest swarm init --v3-mode
331 
332# Search memory (HNSW-indexed)
333npx @claude-flow/cli@latest memory search --query &quot;authentication patterns&quot;
334 
335# System diagnostics
336npx @claude-flow/cli@latest doctor --fix
337 
338# Security scan
339npx @claude-flow/cli@latest security scan --depth full
340 
341# Performance benchmark
342npx @claude-flow/cli@latest performance benchmark --suite all
343```
344 
345## 🚀 Available Agents (60+ Types)
346 
347### Core Development
348`coder`, `reviewer`, `tester`, `planner`, `researcher`
349 
350### V3 Specialized Agents
351`security-architect`, `security-auditor`, `memory-specialist`, `performance-engineer`
352 
353### 🔐 @claude-flow/security
354CVE remediation, input validation, path security:
355- `InputValidator` - Zod validation
356- `PathValidator` - Traversal prevention
357- `SafeExecutor` - Injection protection
358 
359### Swarm Coordination
360`hierarchical-coordinator`, `mesh-coordinator`, `adaptive-coordinator`, `collective-intelligence-coordinator`, `swarm-memory-manager`
361 
362### Consensus & Distributed
363`byzantine-coordinator`, `raft-manager`, `gossip-coordinator`, `consensus-builder`, `crdt-synchronizer`, `quorum-manager`, `security-manager`
364 
365### Performance & Optimization
366`perf-analyzer`, `performance-benchmarker`, `task-orchestrator`, `memory-coordinator`, `smart-agent`
367 
368### GitHub & Repository
369`github-modes`, `pr-manager`, `code-review-swarm`, `issue-tracker`, `release-manager`, `workflow-automation`, `project-board-sync`, `repo-architect`, `multi-repo-swarm`
370 
371### SPARC Methodology
372`sparc-coord`, `sparc-coder`, `specification`, `pseudocode`, `architecture`, `refinement`
373 
374### Specialized Development
375`backend-dev`, `mobile-dev`, `ml-developer`, `cicd-engineer`, `api-docs`, `system-architect`, `code-analyzer`, `base-template-generator`
376 
377### Testing & Validation
378`tdd-london-swarm`, `production-validator`
379 
380## 🪝 V3 Hooks System (27 Hooks + 12 Workers)
381 
382### All Available Hooks
383 
384| Hook | Description | Key Options |
385|------|-------------|-------------|
386| `pre-edit` | Get context before editing files | `--file`, `--operation` |
387| `post-edit` | Record editing outcome for learning | `--file`, `--success`, `--train-neural` |
388| `pre-command` | Assess risk before commands | `--command`, `--validate-safety` |
389| `post-command` | Record command execution outcome | `--command`, `--track-metrics` |
390| `pre-task` | Record task start, get agent suggestions | `--description`, `--coordinate-swarm` |
391| `post-task` | Record task completion for learning | `--task-id`, `--success`, `--store-results` |
392| `session-start` | Start/restore session (v2 compat) | `--session-id`, `--auto-configure` |
393| `session-end` | End session and persist state | `--generate-summary`, `--export-metrics` |
394| `session-restore` | Restore a previous session | `--session-id`, `--latest` |
395| `route` | Route task to optimal agent | `--task`, `--context`, `--top-k` |
396| `route-task` | (v2 compat) Alias for route | `--task`, `--auto-swarm` |
397| `explain` | Explain routing decision | `--topic`, `--detailed` |
398| `pretrain` | Bootstrap intelligence from repo | `--model-type`, `--epochs` |
399| `build-agents` | Generate optimized agent configs | `--agent-types`, `--focus` |
400| `metrics` | View learning metrics dashboard | `--v3-dashboard`, `--format` |
401| `transfer` | Transfer patterns via IPFS registry | `store`, `from-project` |
402| `list` | List all registered hooks | `--format` |
403| `intelligence` | RuVector intelligence system | `trajectory-*`, `pattern-*`, `stats` |
404| `worker` | Background worker management | `list`, `dispatch`, `status`, `detect` |
405| `progress` | Check V3 implementation progress | `--detailed`, `--format` |
406| `statusline` | Generate dynamic statusline | `--json`, `--compact`, `--no-color` |
407| `coverage-route` | Route based on test coverage gaps | `--task`, `--path` |
408| `coverage-suggest` | Suggest coverage improvements | `--path` |
409| `coverage-gaps` | List coverage gaps with priorities | `--format`, `--limit` |
410| `pre-bash` | (v2 compat) Alias for pre-command | Same as pre-command |
411| `post-bash` | (v2 compat) Alias for post-command | Same as post-command |
412 
413### 12 Background Workers
414 
415| Worker | Priority | Description |
416|--------|----------|-------------|
417| `ultralearn` | normal | Deep knowledge acquisition |
418| `optimize` | high | Performance optimization |
419| `consolidate` | low | Memory consolidation |
420| `predict` | normal | Predictive preloading |
421| `audit` | critical | Security analysis |
422| `map` | normal | Codebase mapping |
423| `preload` | low | Resource preloading |
424| `deepdive` | normal | Deep code analysis |
425| `document` | normal | Auto-documentation |
426| `refactor` | normal | Refactoring suggestions |
427| `benchmark` | normal | Performance benchmarking |
428| `testgaps` | normal | Test coverage analysis |
429 
430### Essential Hook Commands
431 
432```bash
433# Core hooks
434npx @claude-flow/cli@latest hooks pre-task --description &quot;[task]&quot;
435npx @claude-flow/cli@latest hooks post-task --task-id &quot;[id]&quot; --success true
436npx @claude-flow/cli@latest hooks post-edit --file &quot;[file]&quot; --train-neural true
437 
438# Session management
439npx @claude-flow/cli@latest hooks session-start --session-id &quot;[id]&quot;
440npx @claude-flow/cli@latest hooks session-end --export-metrics true
441npx @claude-flow/cli@latest hooks session-restore --session-id &quot;[id]&quot;
442 
443# Intelligence routing
444npx @claude-flow/cli@latest hooks route --task &quot;[task]&quot;
445npx @claude-flow/cli@latest hooks explain --topic &quot;[topic]&quot;
446 
447# Neural learning
448npx @claude-flow/cli@latest hooks pretrain --model-type moe --epochs 10
449npx @claude-flow/cli@latest hooks build-agents --agent-types coder,tester
450 
451# Background workers
452npx @claude-flow/cli@latest hooks worker list
453npx @claude-flow/cli@latest hooks worker dispatch --trigger audit
454npx @claude-flow/cli@latest hooks worker status
455 
456# Coverage-aware routing
457npx @claude-flow/cli@latest hooks coverage-gaps --format table
458npx @claude-flow/cli@latest hooks coverage-route --task &quot;[task]&quot;
459 
460# Statusline (for Claude Code integration)
461npx @claude-flow/cli@latest hooks statusline
462npx @claude-flow/cli@latest hooks statusline --json
463```
464 
465## 🔄 Migration (V2 to V3)
466 
467```bash
468# Check migration status
469npx @claude-flow/cli@latest migrate status
470 
471# Run migration with backup
472npx @claude-flow/cli@latest migrate run --backup
473 
474# Rollback if needed
475npx @claude-flow/cli@latest migrate rollback
476 
477# Validate migration
478npx @claude-flow/cli@latest migrate validate
479```
480 
481## 🧠 Intelligence System (RuVector)
482 
483V3 includes the RuVector Intelligence System:
484- **SONA**: Self-Optimizing Neural Architecture (<0.05ms adaptation)
485- **MoE**: Mixture of Experts for specialized routing
486- **HNSW**: 150x-12,500x faster pattern search
487- **EWC++**: Elastic Weight Consolidation (prevents forgetting)
488- **Flash Attention**: 2.49x-7.47x speedup
489 
490The 4-step intelligence pipeline:
4911. **RETRIEVE** - Fetch relevant patterns via HNSW
4922. **JUDGE** - Evaluate with verdicts (success/failure)
4933. **DISTILL** - Extract key learnings via LoRA
4944. **CONSOLIDATE** - Prevent catastrophic forgetting via EWC++
495 
496## 📦 Embeddings Package (v3.0.0-alpha.12)
497 
498Features:
499- **sql.js**: Cross-platform SQLite persistent cache (WASM, no native compilation)
500- **Document chunking**: Configurable overlap and size
501- **Normalization**: L2, L1, min-max, z-score
502- **Hyperbolic embeddings**: Poincaré ball model for hierarchical data
503- **75x faster**: With agentic-flow ONNX integration
504- **Neural substrate**: Integration with RuVector
505 
506## 🐝 Hive-Mind Consensus
507 
508### Topologies
509- `hierarchical` - Queen controls workers directly
510- `mesh` - Fully connected peer network
511- `hierarchical-mesh` - Hybrid (recommended)
512- `adaptive` - Dynamic based on load
513 
514### Consensus Strategies
515- `byzantine` - BFT (tolerates f < n/3 faulty)
516- `raft` - Leader-based (tolerates f < n/2)
517- `gossip` - Epidemic for eventual consistency
518- `crdt` - Conflict-free replicated data types
519- `quorum` - Configurable quorum-based
520 
521## V3 Performance Targets
522 
523| Metric | Target |
524|--------|--------|
525| Flash Attention | 2.49x-7.47x speedup |
526| HNSW Search | 150x-12,500x faster |
527| Memory Reduction | 50-75% with quantization |
528| MCP Response | <100ms |
529| CLI Startup | <500ms |
530| SONA Adaptation | <0.05ms |
531 
532## 📊 Performance Optimization Protocol
533 
534### Automatic Performance Tracking
535```bash
536# After any significant operation, track metrics
537Bash(&quot;npx @claude-flow/cli@latest hooks post-command --command '[operation]' --track-metrics true&quot;)
538 
539# Periodically run benchmarks (every major feature)
540Bash(&quot;npx @claude-flow/cli@latest performance benchmark --suite all&quot;)
541 
542# Analyze bottlenecks when performance degrades
543Bash(&quot;npx @claude-flow/cli@latest performance profile --target '[component]'&quot;)
544```
545 
546### Session Persistence (Cross-Conversation Learning)
547```bash
548# At session start - restore previous context
549Bash(&quot;npx @claude-flow/cli@latest session restore --latest&quot;)
550 
551# At session end - persist learned patterns
552Bash(&quot;npx @claude-flow/cli@latest hooks session-end --generate-summary true --persist-state true --export-metrics true&quot;)
553```
554 
555### Neural Pattern Training
556```bash
557# Train on successful code patterns
558Bash(&quot;npx @claude-flow/cli@latest neural train --pattern-type coordination --epochs 10&quot;)
559 
560# Predict optimal approach for new tasks
561Bash(&quot;npx @claude-flow/cli@latest neural predict --input '[task description]'&quot;)
562 
563# View learned patterns
564Bash(&quot;npx @claude-flow/cli@latest neural patterns --list&quot;)
565```
566 
567## 🔧 Environment Variables
568 
569```bash
570# Configuration
571CLAUDE_FLOW_CONFIG=./claude-flow.config.json
572CLAUDE_FLOW_LOG_LEVEL=info
573 
574# Provider API Keys
575ANTHROPIC_API_KEY=sk-ant-...
576OPENAI_API_KEY=sk-...
577GOOGLE_API_KEY=...
578 
579# MCP Server
580CLAUDE_FLOW_MCP_PORT=3000
581CLAUDE_FLOW_MCP_HOST=localhost
582CLAUDE_FLOW_MCP_TRANSPORT=stdio
583 
584# Memory
585CLAUDE_FLOW_MEMORY_BACKEND=hybrid
586CLAUDE_FLOW_MEMORY_PATH=./data/memory
587```
588 
589## 🔍 Doctor Health Checks
590 
591Run `npx @claude-flow/cli@latest doctor` to check:
592- Node.js version (20+)
593- npm version (9+)
594- Git installation
595- Config file validity
596- Daemon status
597- Memory database
598- API keys
599- MCP servers
600- Disk space
601- TypeScript installation
602 
603## 🚀 Quick Setup
604 
605```bash
606# Add MCP servers (auto-detects MCP mode when stdin is piped)
607claude mcp add claude-flow -- npx -y ruflo@latest mcp start
608claude mcp add ruv-swarm -- npx -y ruv-swarm mcp start  # Optional
609claude mcp add flow-nexus -- npx -y flow-nexus@latest mcp start  # Optional
610 
611# Start daemon
612npx @claude-flow/cli@latest daemon start
613 
614# Run doctor
615npx @claude-flow/cli@latest doctor --fix
616```
617 
618## 🎯 Claude Code vs CLI Tools
619 
620### Claude Code Handles ALL EXECUTION:
621- **Task tool**: Spawn and run agents concurrently
622- File operations (Read, Write, Edit, MultiEdit, Glob, Grep)
623- Code generation and programming
624- Bash commands and system operations
625- TodoWrite and task management
626- Git operations
627 
628### CLI Tools Handle Coordination (via Bash):
629- **Swarm init**: `npx @claude-flow/cli@latest swarm init --topology <type>`
630- **Swarm status**: `npx @claude-flow/cli@latest swarm status`
631- **Agent spawn**: `npx @claude-flow/cli@latest agent spawn -t <type> --name <name>`
632- **Memory store**: `npx @claude-flow/cli@latest memory store --key "mykey" --value "myvalue" --namespace patterns`
633- **Memory search**: `npx @claude-flow/cli@latest memory search --query "search terms"`
634- **Memory list**: `npx @claude-flow/cli@latest memory list --namespace patterns`
635- **Memory retrieve**: `npx @claude-flow/cli@latest memory retrieve --key "mykey" --namespace patterns`
636- **Hooks**: `npx @claude-flow/cli@latest hooks <hook-name> [options]`
637 
638## 📝 Memory Commands Reference (IMPORTANT)
639 
640### Store Data (ALL options shown)
641```bash
642# REQUIRED: --key and --value
643# OPTIONAL: --namespace (default: "default"), --ttl, --tags
644npx @claude-flow/cli@latest memory store --key &quot;pattern-auth&quot; --value &quot;JWT with refresh tokens&quot; --namespace patterns
645npx @claude-flow/cli@latest memory store --key &quot;bug-fix-123&quot; --value &quot;Fixed null check&quot; --namespace solutions --tags &quot;bugfix,auth&quot;
646```
647 
648### Search Data (semantic vector search)
649```bash
650# REQUIRED: --query (full flag, not -q)
651# OPTIONAL: --namespace, --limit, --threshold
652npx @claude-flow/cli@latest memory search --query &quot;authentication patterns&quot;
653npx @claude-flow/cli@latest memory search --query &quot;error handling&quot; --namespace patterns --limit 5
654```
655 
656### List Entries
657```bash
658# OPTIONAL: --namespace, --limit
659npx @claude-flow/cli@latest memory list
660npx @claude-flow/cli@latest memory list --namespace patterns --limit 10
661```
662 
663### Retrieve Specific Entry
664```bash
665# REQUIRED: --key
666# OPTIONAL: --namespace (default: "default")
667npx @claude-flow/cli@latest memory retrieve --key &quot;pattern-auth&quot;
668npx @claude-flow/cli@latest memory retrieve --key &quot;pattern-auth&quot; --namespace patterns
669```
670 
671### Initialize Memory Database
672```bash
673npx @claude-flow/cli@latest memory init --force --verbose
674```
675 
676**KEY**: CLI coordinates the strategy via Bash, Claude Code's Task tool executes with real agents.
677 
678## Support
679 
680- Documentation: https://github.com/ruvnet/claude-flow
681- Issues: https://github.com/ruvnet/claude-flow/issues
682 
683---
684 
685Remember: **Claude Flow CLI coordinates, Claude Code Task tool creates!**
686 
687# important-instruction-reminders
688Do what has been asked; nothing more, nothing less.
689NEVER create files unless they're absolutely necessary for achieving your goal.
690ALWAYS prefer editing an existing file to creating a new one.
691NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
692Never save working files, text/mds and tests to the root folder.
693 
694## 🚨 SWARM EXECUTION RULES (CRITICAL)
6951. **SPAWN IN BACKGROUND**: Use `run_in_background: true` for all agent Task calls
6962. **SPAWN ALL AT ONCE**: Put ALL agent Task calls in ONE message for parallel execution
6973. **TELL USER**: After spawning, list what each agent is doing (use emojis for clarity)
6984. **STOP AND WAIT**: After spawning, STOP - do NOT add more tool calls or check status
6995. **NO POLLING**: Never poll TaskOutput or check swarm status - trust agents to return
7006. **SYNTHESIZE**: When agent results arrive, review ALL results before proceeding
7017. **NO CONFIRMATION**: Don't ask "should I check?" - just wait for results
702 
703Example spawn message:
704```
705"I've launched 4 agents in background:
706- 🔍 Researcher: [task]
707- 💻 Coder: [task]
708- 🧪 Tester: [task]
709- 👀 Reviewer: [task]
710Working in parallel - I'll synthesize when they complete."
711```
712