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