Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

Checkpoint: File edits

rUv3b91cdc41135
diff --git a/v3/@claude-flow/cli/.claude/helpers/statusline-hook.sh b/v3/@claude-flow/cli/.claude/helpers/statusline-hook.sh
old mode 100644
new mode 100755
diff --git a/v3/@claude-flow/cli/.claude/helpers/statusline.js b/v3/@claude-flow/cli/.claude/helpers/statusline.js
index 018ec419fb..849aeddbce 100644
--- a/v3/@claude-flow/cli/.claude/helpers/statusline.js
+++ b/v3/@claude-flow/cli/.claude/helpers/statusline.js
@@ -78,7 +78,7 @@ function getLearningStats() {
// Count entries in memory file (rough estimate from file size)
const stats = fs.statSync(dbPath);
const sizeKB = stats.size / 1024;
- // Estimate: ~1KB per pattern on average
+ // Estimate: ~2KB per pattern on average
patterns = Math.floor(sizeKB / 2);
sessions = Math.max(1, Math.floor(patterns / 10));
trajectories = Math.floor(patterns / 5);
@@ -103,7 +103,7 @@ function getLearningStats() {
return { patterns, sessions, trajectories };
}
-// Get V3 progress from learning state (not hardcoded)
+// Get V3 progress from learning state (grows as system learns)
function getV3Progress() {
const learning = getLearningStats();
@@ -186,7 +186,7 @@ function getSwarmStatus() {
};
}
-// Get system metrics (all dynamic, no hardcoded values)
+// Get system metrics (dynamic based on actual state)
function getSystemMetrics() {
let memoryMB = 0;
let subAgents = 0;
diff --git a/v3/@claude-flow/cli/.claude/settings.json b/v3/@claude-flow/cli/.claude/settings.json
index c75e077935..dbef2c25e3 100644
--- a/v3/@claude-flow/cli/.claude/settings.json
+++ b/v3/@claude-flow/cli/.claude/settings.json
@@ -6,7 +6,7 @@
"hooks": [
{
"type": "command",
- "command": "npx claude-flow@v3alpha hooks pre-edit --file \"$TOOL_INPUT_file_path\" --intelligence",
+ "command": "[ -n \"$TOOL_INPUT_file_path\" ] && npx @claude-flow/cli@latest hooks pre-edit --file \"$TOOL_INPUT_file_path\" 2>/dev/null || true",
"timeout": 5000,
"continueOnError": true
}
@@ -17,7 +17,7 @@
"hooks": [
{
"type": "command",
- "command": "npx claude-flow@v3alpha hooks pre-command --command \"$TOOL_INPUT_command\"",
+ "command": "[ -n \"$TOOL_INPUT_command\" ] && npx @claude-flow/cli@latest hooks pre-command --command \"$TOOL_INPUT_command\" 2>/dev/null || true",
"timeout": 5000,
"continueOnError": true
}
@@ -28,22 +28,11 @@
"hooks": [
{
"type": "command",
- "command": "npx claude-flow@v3alpha hooks pre-task --task-id \"task-$(date +%s)\" --description \"$TOOL_INPUT_prompt\"",
+ "command": "[ -n \"$TOOL_INPUT_prompt\" ] && npx @claude-flow/cli@latest hooks pre-task --task-id \"task-$(date +%s)\" --description \"$TOOL_INPUT_prompt\" 2>/dev/null || true",
"timeout": 5000,
"continueOnError": true
}
]
- },
- {
- "matcher": "^(Grep|Glob|Read)$",
- "hooks": [
- {
- "type": "command",
- "command": "npx claude-flow@v3alpha hooks pre-search --pattern \"$TOOL_INPUT_pattern\"",
- "timeout": 2000,
- "continueOnError": true
- }
- ]
}
],
"PostToolUse": [
@@ -52,7 +41,7 @@
"hooks": [
{
"type": "command",
- "command": "npx claude-flow@v3alpha hooks post-edit --file \"$TOOL_INPUT_file_path\" --success \"$TOOL_SUCCESS\" --train-patterns",
+ "command": "[ -n \"$TOOL_INPUT_file_path\" ] && npx @claude-flow/cli@latest hooks post-edit --file \"$TOOL_INPUT_file_path\" --success \"${TOOL_SUCCESS:-true}\" 2>/dev/null || true",
"timeout": 5000,
"continueOnError": true
}
@@ -63,7 +52,7 @@
"hooks": [
{
"type": "command",
- "command": "npx claude-flow@v3alpha hooks post-command --command \"$TOOL_INPUT_command\" --success \"$TOOL_SUCCESS\" --exit-code \"$TOOL_EXIT_CODE\"",
+ "command": "[ -n \"$TOOL_INPUT_command\" ] && npx @claude-flow/cli@latest hooks post-command --command \"$TOOL_INPUT_command\" --success \"${TOOL_SUCCESS:-true}\" 2>/dev/null || true",
"timeout": 5000,
"continueOnError": true
}
@@ -74,22 +63,11 @@
"hooks": [
{
"type": "command",
- "command": "npx claude-flow@v3alpha hooks post-task --agent-id \"$TOOL_RESULT_agent_id\" --success \"$TOOL_SUCCESS\" --analyze",
+ "command": "[ -n \"$TOOL_RESULT_agent_id\" ] && npx @claude-flow/cli@latest hooks post-task --task-id \"$TOOL_RESULT_agent_id\" --success \"${TOOL_SUCCESS:-true}\" 2>/dev/null || true",
"timeout": 5000,
"continueOnError": true
}
]
- },
- {
- "matcher": "^(Grep|Glob)$",
- "hooks": [
- {
- "type": "command",
- "command": "npx claude-flow@v3alpha hooks post-search --cache-results",
- "timeout": 2000,
- "continueOnError": true
- }
- ]
}
],
"UserPromptSubmit": [
@@ -97,7 +75,7 @@
"hooks": [
{
"type": "command",
- "command": "npx claude-flow@v3alpha hooks route --task \"$PROMPT\" --intelligence --include-explanation",
+ "command": "[ -n \"$PROMPT\" ] && npx @claude-flow/cli@latest hooks route --task \"$PROMPT\" || true",
"timeout": 5000,
"continueOnError": true
}
@@ -109,13 +87,13 @@
"hooks": [
{
"type": "command",
- "command": "npx claude-flow@v3alpha daemon start --quiet 2>/dev/null || true",
+ "command": "npx @claude-flow/cli@latest daemon start --quiet 2>/dev/null || true",
"timeout": 5000,
"continueOnError": true
},
{
"type": "command",
- "command": "npx claude-flow@v3alpha hooks session-start --session-id \"$SESSION_ID\" --load-context",
+ "command": "[ -n \"$SESSION_ID\" ] && npx @claude-flow/cli@latest hooks session-restore --session-id \"$SESSION_ID\" 2>/dev/null || true",
"timeout": 10000,
"continueOnError": true
}
@@ -126,8 +104,9 @@
{
"hooks": [
{
- "type": "prompt",
- "prompt": "Evaluate task completion. Consider:\n1. Were all requested changes made?\n2. Did builds/tests pass?\n3. Is follow-up work needed?\n\nRespond with {\"decision\": \"stop\"} if complete, or {\"decision\": \"continue\", \"reason\": \"...\"} if more work is needed."
+ "type": "command",
+ "command": "echo '{\"ok\": true}'",
+ "timeout": 1000
}
]
}
@@ -137,7 +116,7 @@
"hooks": [
{
"type": "command",
- "command": "npx claude-flow@v3alpha hooks notify --message \"$NOTIFICATION_MESSAGE\" --swarm-status",
+ "command": "[ -n \"$NOTIFICATION_MESSAGE\" ] && npx @claude-flow/cli@latest memory store --namespace notifications --key \"notify-$(date +%s)\" --value \"$NOTIFICATION_MESSAGE\" 2>/dev/null || true",
"timeout": 3000,
"continueOnError": true
}
@@ -168,6 +147,7 @@
]
},
"statusLine": {
+ "type": "command",
"command": "npx @claude-flow/hooks statusline 2>/dev/null || node .claude/helpers/statusline.js 2>/dev/null || echo \"β–Š V3\"",
"refreshMs": 5000,
"enabled": true
@@ -185,7 +165,7 @@
"enabled": true,
"modelPreferences": {
"default": "claude-opus-4-5-20251101",
- "routing": "claude-3-5-haiku-20241022"
+ "routing": "claude-opus-4-5-20251101"
},
"swarm": {
"topology": "hierarchical-mesh",
@@ -205,8 +185,75 @@
"audit",
"optimize",
"consolidate",
- "testgaps"
- ]
+ "testgaps",
+ "ultralearn",
+ "deepdive",
+ "document",
+ "refactor",
+ "benchmark"
+ ],
+ "schedules": {
+ "audit": {
+ "interval": "1h",
+ "priority": "critical"
+ },
+ "optimize": {
+ "interval": "30m",
+ "priority": "high"
+ },
+ "consolidate": {
+ "interval": "2h",
+ "priority": "low"
+ },
+ "document": {
+ "interval": "1h",
+ "priority": "normal",
+ "triggers": [
+ "adr-update",
+ "api-change"
+ ]
+ },
+ "deepdive": {
+ "interval": "4h",
+ "priority": "normal",
+ "triggers": [
+ "complex-change"
+ ]
+ },
+ "ultralearn": {
+ "interval": "1h",
+ "priority": "normal"
+ }
+ }
+ },
+ "learning": {
+ "enabled": true,
+ "autoTrain": true,
+ "patterns": [
+ "coordination",
+ "optimization",
+ "prediction"
+ ],
+ "retention": {
+ "shortTerm": "24h",
+ "longTerm": "30d"
+ }
+ },
+ "adr": {
+ "autoGenerate": true,
+ "directory": "/docs/adr",
+ "template": "madr"
+ },
+ "ddd": {
+ "trackDomains": true,
+ "validateBoundedContexts": true,
+ "directory": "/docs/ddd"
+ },
+ "security": {
+ "autoScan": true,
+ "scanOnEdit": true,
+ "cveCheck": true,
+ "threatModel": true
}
}
}
\ No newline at end of file
diff --git a/v3/@claude-flow/cli/CLAUDE.md b/v3/@claude-flow/cli/CLAUDE.md
index 0a33c8b6ec..23a74d71a8 100644
--- a/v3/@claude-flow/cli/CLAUDE.md
+++ b/v3/@claude-flow/cli/CLAUDE.md
@@ -4,59 +4,152 @@
**When starting work on complex tasks, Claude Code MUST automatically:**
-1. **Initialize the swarm** using MCP tools
+1. **Initialize the swarm** using CLI tools via Bash
2. **Spawn concurrent agents** using Claude Code's Task tool
3. **Coordinate via hooks** and memory
-### 🚨 CRITICAL: MCP + Task Tool in SAME Message
+### 🚨 CRITICAL: CLI + Task Tool in SAME Message
**When user says "spawn swarm" or requests complex work, Claude Code MUST in ONE message:**
-1. Call MCP tools to initialize coordination
+1. Call CLI tools via Bash to initialize coordination
2. **IMMEDIATELY** call Task tool to spawn REAL working agents
-3. Both MCP and Task calls must be in the SAME response
+3. Both CLI and Task calls must be in the SAME response
-**MCP alone does NOT execute work - Task tool agents do the actual work!**
+**CLI coordinates, Task tool agents do the actual work!**
-### πŸ”„ Auto-Start Swarm Protocol
+### πŸ”„ Auto-Start Swarm Protocol (Background Execution)
-When the user requests a complex task (multi-file changes, feature implementation, refactoring), **immediately execute this pattern in a SINGLE message:**
+When the user requests a complex task, **spawn agents in background and WAIT for completion:**
```javascript
-// STEP 1: Initialize swarm coordination via MCP (in parallel with agent spawning)
-mcp__claude-flow__swarm_init({
- topology: "hierarchical",
- maxAgents: 15,
- strategy: "adaptive"
+// STEP 1: Initialize swarm coordination
+Bash("npx @claude-flow/cli@latest swarm init --topology hierarchical-mesh --max-agents 15")
+
+// STEP 2: Spawn ALL agents IN BACKGROUND in a SINGLE message
+// Use run_in_background: true so agents work concurrently
+Task({
+ prompt: "Research requirements, analyze codebase patterns, store findings in memory",
+ subagent_type: "researcher",
+ description: "Research phase",
+ run_in_background: true // ← CRITICAL: Run in background
})
-
-// 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()})
+Task({
+ prompt: "Design architecture based on research. Document decisions.",
+ subagent_type: "system-architect",
+ description: "Architecture phase",
+ run_in_background: true
+})
+Task({
+ prompt: "Implement the solution following the design. Write clean code.",
+ subagent_type: "coder",
+ description: "Implementation phase",
+ run_in_background: true
+})
+Task({
+ prompt: "Write comprehensive tests for the implementation.",
+ subagent_type: "tester",
+ description: "Testing phase",
+ run_in_background: true
+})
+Task({
+ prompt: "Review code quality, security, and best practices.",
+ subagent_type: "reviewer",
+ description: "Review phase",
+ run_in_background: true
})
+
+// STEP 3: WAIT - Tell user agents are working, then STOP
+// Say: "I've spawned 5 agents to work on this in parallel. They'll report back when done."
+// DO NOT check status repeatedly. Just wait for user or agent responses.
+```
+
+### ⏸️ CRITICAL: Spawn and Wait Pattern
+
+**After spawning background agents:**
+
+1. **TELL USER** - "I've spawned X agents working in parallel on: [list tasks]"
+2. **STOP** - Do not continue with more tool calls
+3. **WAIT** - Let the background agents complete their work
+4. **RESPOND** - When agents return results, review and synthesize
+
+**Example response after spawning:**
+```
+I've launched 5 concurrent agents to work on this:
+- πŸ” Researcher: Analyzing requirements and codebase
+- πŸ—οΈ Architect: Designing the implementation approach
+- πŸ’» Coder: Implementing the solution
+- πŸ§ͺ Tester: Writing tests
+- πŸ‘€ Reviewer: Code review and security check
+
+They're working in parallel. I'll synthesize their results when they complete.
+```
+
+### 🚫 DO NOT:
+- Continuously check swarm status
+- Poll TaskOutput repeatedly
+- Add more tool calls after spawning
+- Ask "should I check on the agents?"
+
+### βœ… DO:
+- Spawn all agents in ONE message
+- Tell user what's happening
+- Wait for agent results to arrive
+- Synthesize results when they return
+
+## 🧠 AUTO-LEARNING PROTOCOL
+
+### Before Starting Any Task
+```bash
+# 1. Search memory for relevant patterns from past successes
+Bash("npx @claude-flow/cli@latest memory search -q '[task keywords]' --namespace patterns")
+
+# 2. Check if similar task was done before
+Bash("npx @claude-flow/cli@latest memory search -q '[task type]' --namespace tasks")
+
+# 3. Load learned optimizations
+Bash("npx @claude-flow/cli@latest hooks route --task '[task description]'")
+```
+
+### After Completing Any Task Successfully
+```bash
+# 1. Store successful pattern for future reference
+Bash("npx @claude-flow/cli@latest memory store --namespace patterns --key '[pattern-name]' --value '[what worked]'")
+
+# 2. Train neural patterns on the successful approach
+Bash("npx @claude-flow/cli@latest hooks post-edit --file '[main-file]' --train-neural true")
+
+# 3. Record task completion with metrics
+Bash("npx @claude-flow/cli@latest hooks post-task --task-id '[id]' --success true --store-results true")
+
+# 4. Trigger optimization worker if performance-related
+Bash("npx @claude-flow/cli@latest hooks worker dispatch --trigger optimize")
```
+### Continuous Improvement Triggers
+
+| Trigger | Worker | When to Use |
+|---------|--------|-------------|
+| After major refactor | `optimize` | Performance optimization |
+| After adding features | `testgaps` | Find missing test coverage |
+| After security changes | `audit` | Security analysis |
+| After API changes | `document` | Update documentation |
+| Every 5+ file changes | `map` | Update codebase map |
+| Complex debugging | `deepdive` | Deep code analysis |
+
+### Memory-Enhanced Development
+
+**ALWAYS check memory before:**
+- Starting a new feature (search for similar implementations)
+- Debugging an issue (search for past solutions)
+- Refactoring code (search for learned patterns)
+- Performance work (search for optimization strategies)
+
+**ALWAYS store in memory after:**
+- Solving a tricky bug (store the solution pattern)
+- Completing a feature (store the approach)
+- Finding a performance fix (store the optimization)
+- Discovering a security issue (store the vulnerability pattern)
+
### πŸ“‹ Agent Routing by Task Type
| Task Type | Required Agents | Topology |
@@ -117,9 +210,9 @@ mcp__claude-flow__memory_usage({
## Project Configuration
This project is configured with Claude Flow V3:
-- **Topology**: hierarchical
+- **Topology**: hierarchical-mesh
- **Max Agents**: 15
-- **Memory Backend**: hybrid (SQLite + AgentDB)
+- **Memory Backend**: hybrid
- **HNSW Indexing**: Enabled (150x-12,500x faster)
- **Neural Learning**: Enabled (SONA)
@@ -138,7 +231,6 @@ This project is configured with Claude Flow V3:
| `session` | 7 | Session state management and persistence |
| `config` | 7 | Configuration management and provider setup |
| `status` | 3 | System status monitoring with watch mode |
-| `start` | 3 | Service startup and quick launch |
| `workflow` | 6 | Workflow execution and template management |
| `hooks` | 17 | Self-learning hooks + 12 background workers |
| `hive-mind` | 6 | Queen-led Byzantine fault-tolerant consensus |
@@ -157,7 +249,6 @@ This project is configured with Claude Flow V3:
| `embeddings` | 4 | Vector embeddings (embed, batch, search, init) - 75x faster with agentic-flow |
| `claims` | 4 | Claims-based authorization (check, grant, revoke, list) |
| `migrate` | 5 | V2 to V3 migration with rollback support |
-| `process` | 4 | Background process management |
| `doctor` | 1 | System diagnostics with health checks |
| `completions` | 4 | Shell completions (bash, zsh, fish, powershell) |
@@ -165,28 +256,28 @@ This project is configured with Claude Flow V3:
```bash
# Initialize project
-npx claude-flow@v3alpha init --wizard
+npx @claude-flow/cli@latest init --wizard
# Start daemon with background workers
-npx claude-flow@v3alpha daemon start
+npx @claude-flow/cli@latest daemon start
# Spawn an agent
-npx claude-flow@v3alpha agent spawn -t coder --name my-coder
+npx @claude-flow/cli@latest agent spawn -t coder --name my-coder
# Initialize swarm
-npx claude-flow@v3alpha swarm init --v3-mode
+npx @claude-flow/cli@latest swarm init --v3-mode
# Search memory (HNSW-indexed)
-npx claude-flow@v3alpha memory search -q "authentication patterns"
+npx @claude-flow/cli@latest memory search -q "authentication patterns"
# System diagnostics
-npx claude-flow@v3alpha doctor --fix
+npx @claude-flow/cli@latest doctor --fix
# Security scan
-npx claude-flow@v3alpha security scan --depth full
+npx @claude-flow/cli@latest security scan --depth full
# Performance benchmark
-npx claude-flow@v3alpha performance benchmark --suite all
+npx @claude-flow/cli@latest performance benchmark --suite all
```
## πŸš€ Available Agents (60+ Types)
@@ -250,27 +341,27 @@ npx claude-flow@v3alpha performance benchmark --suite all
```bash
# 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
+npx @claude-flow/cli@latest hooks pre-task --description "[task]"
+npx @claude-flow/cli@latest hooks post-task --task-id "[id]" --success true
+npx @claude-flow/cli@latest 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]"
+npx @claude-flow/cli@latest hooks session-start --session-id "[id]"
+npx @claude-flow/cli@latest hooks session-end --export-metrics true
+npx @claude-flow/cli@latest hooks session-restore --session-id "[id]"
# Intelligence routing
-npx claude-flow@v3alpha hooks route --task "[task]"
-npx claude-flow@v3alpha hooks explain --topic "[topic]"
+npx @claude-flow/cli@latest hooks route --task "[task]"
+npx @claude-flow/cli@latest 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
+npx @claude-flow/cli@latest hooks pretrain --model-type moe --epochs 10
+npx @claude-flow/cli@latest 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
+npx @claude-flow/cli@latest hooks worker list
+npx @claude-flow/cli@latest hooks worker dispatch --trigger audit
+npx @claude-flow/cli@latest hooks worker status
```
## 🧠 Intelligence System (RuVector)
@@ -324,6 +415,41 @@ Features:
| CLI Startup | <500ms |
| SONA Adaptation | <0.05ms |
+## πŸ“Š Performance Optimization Protocol
+
+### Automatic Performance Tracking
+```bash
+# After any significant operation, track metrics
+Bash("npx @claude-flow/cli@latest hooks post-command --command '[operation]' --track-metrics true")
+
+# Periodically run benchmarks (every major feature)
+Bash("npx @claude-flow/cli@latest performance benchmark --suite all")
+
+# Analyze bottlenecks when performance degrades
+Bash("npx @claude-flow/cli@latest performance profile --target '[component]'")
+```
+
+### Session Persistence (Cross-Conversation Learning)
+```bash
+# At session start - restore previous context
+Bash("npx @claude-flow/cli@latest session restore --latest")
+
+# At session end - persist learned patterns
+Bash("npx @claude-flow/cli@latest hooks session-end --generate-summary true --persist-state true --export-metrics true")
+```
+
+### Neural Pattern Training
+```bash
+# Train on successful code patterns
+Bash("npx @claude-flow/cli@latest neural train --pattern-type coordination --epochs 10")
+
+# Predict optimal approach for new tasks
+Bash("npx @claude-flow/cli@latest neural predict --input '[task description]'")
+
+# View learned patterns
+Bash("npx @claude-flow/cli@latest neural patterns --list")
+```
+
## πŸ”§ Environment Variables
```bash
@@ -348,7 +474,7 @@ CLAUDE_FLOW_MEMORY_PATH=./data/memory
## πŸ” Doctor Health Checks
-Run `npx claude-flow@v3alpha doctor` to check:
+Run `npx @claude-flow/cli@latest doctor` to check:
- Node.js version (20+)
- npm version (9+)
- Git installation
@@ -363,19 +489,19 @@ Run `npx claude-flow@v3alpha doctor` to check:
## πŸš€ Quick Setup
```bash
-# 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
+# Add MCP servers (auto-detects MCP mode when stdin is piped)
+claude mcp add claude-flow -- npx -y @claude-flow/cli@latest
+claude mcp add ruv-swarm -- npx -y ruv-swarm mcp start # Optional
+claude mcp add flow-nexus -- npx -y flow-nexus@latest mcp start # Optional
# Start daemon
-npx claude-flow@v3alpha daemon start
+npx @claude-flow/cli@latest daemon start
# Run doctor
-npx claude-flow@v3alpha doctor --fix
+npx @claude-flow/cli@latest doctor --fix
```
-## 🎯 Claude Code vs MCP Tools
+## 🎯 Claude Code vs CLI Tools
### Claude Code Handles ALL EXECUTION:
- **Task tool**: Spawn and run agents concurrently
@@ -385,15 +511,15 @@ npx claude-flow@v3alpha doctor --fix
- TodoWrite and task management
- Git operations
-### MCP Tools ONLY COORDINATE:
-- Swarm initialization (topology setup)
-- Agent type definitions
-- Task orchestration
-- Memory management
-- Neural features
-- Performance tracking
+### CLI Tools Handle Coordination (via Bash):
+- **Swarm init**: `npx @claude-flow/cli@latest swarm init --topology <type>`
+- **Swarm status**: `npx @claude-flow/cli@latest swarm status`
+- **Agent spawn**: `npx @claude-flow/cli@latest agent spawn -t <type> --name <name>`
+- **Memory store**: `npx @claude-flow/cli@latest memory store --namespace <ns> --key <k> --value <v>`
+- **Memory search**: `npx @claude-flow/cli@latest memory search -q "<query>"`
+- **Hooks**: `npx @claude-flow/cli@latest hooks <hook-name> [options]`
-**KEY**: MCP coordinates the strategy, Claude Code's Task tool executes with real agents.
+**KEY**: CLI coordinates the strategy via Bash, Claude Code's Task tool executes with real agents.
## Support
@@ -402,7 +528,7 @@ npx claude-flow@v3alpha doctor --fix
---
-Remember: **Claude Flow coordinates, Claude Code creates!**
+Remember: **Claude Flow CLI coordinates, Claude Code Task tool creates!**
# important-instruction-reminders
Do what has been asked; nothing more, nothing less.
@@ -410,4 +536,22 @@ 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.
+
+## 🚨 SWARM EXECUTION RULES (CRITICAL)
+1. **SPAWN IN BACKGROUND**: Use `run_in_background: true` for all agent Task calls
+2. **SPAWN ALL AT ONCE**: Put ALL agent Task calls in ONE message for parallel execution
+3. **TELL USER**: After spawning, list what each agent is doing (use emojis for clarity)
+4. **STOP AND WAIT**: After spawning, STOP - do NOT add more tool calls or check status
+5. **NO POLLING**: Never poll TaskOutput or check swarm status - trust agents to return
+6. **SYNTHESIZE**: When agent results arrive, review ALL results before proceeding
+7. **NO CONFIRMATION**: Don't ask "should I check?" - just wait for results
+
+Example spawn message:
+```
+"I've launched 4 agents in background:
+- πŸ” Researcher: [task]
+- πŸ’» Coder: [task]
+- πŸ§ͺ Tester: [task]
+- πŸ‘€ Reviewer: [task]
+Working in parallel - I'll synthesize when they complete."
+```
diff --git a/v3/@claude-flow/cli/agents/architect.yaml b/v3/@claude-flow/cli/agents/architect.yaml
index f1bad03aa1..72fb0a9041 100644
--- a/v3/@claude-flow/cli/agents/architect.yaml
+++ b/v3/@claude-flow/cli/agents/architect.yaml
@@ -8,4 +8,4 @@ capabilities:
optimizations:
- context-caching
- memory-persistence
-createdAt: "2026-01-08T19:36:26.907Z"
+createdAt: "2026-01-08T20:52:25.958Z"
diff --git a/v3/@claude-flow/cli/agents/coder.yaml b/v3/@claude-flow/cli/agents/coder.yaml
index af50222306..8cf0e9680e 100644
--- a/v3/@claude-flow/cli/agents/coder.yaml
+++ b/v3/@claude-flow/cli/agents/coder.yaml
@@ -8,4 +8,4 @@ capabilities:
optimizations:
- flash-attention
- token-reduction
-createdAt: "2026-01-08T19:36:26.907Z"
+createdAt: "2026-01-08T20:52:25.958Z"
diff --git a/v3/@claude-flow/cli/agents/reviewer.yaml b/v3/@claude-flow/cli/agents/reviewer.yaml
index 142697dcd8..7bcbbcbb9b 100644
--- a/v3/@claude-flow/cli/agents/reviewer.yaml
+++ b/v3/@claude-flow/cli/agents/reviewer.yaml
@@ -7,4 +7,4 @@ capabilities:
- best-practices
optimizations:
- incremental-analysis
-createdAt: "2026-01-08T19:36:26.907Z"
+createdAt: "2026-01-08T20:52:25.959Z"
diff --git a/v3/@claude-flow/cli/agents/security-architect.yaml b/v3/@claude-flow/cli/agents/security-architect.yaml
index 1ac557a0b2..ede59aab75 100644
--- a/v3/@claude-flow/cli/agents/security-architect.yaml
+++ b/v3/@claude-flow/cli/agents/security-architect.yaml
@@ -7,4 +7,4 @@ capabilities:
- security-review
optimizations:
- pattern-matching
-createdAt: "2026-01-08T19:36:26.907Z"
+createdAt: "2026-01-08T20:52:25.959Z"
diff --git a/v3/@claude-flow/cli/agents/tester.yaml b/v3/@claude-flow/cli/agents/tester.yaml
index 09a63e9505..01531c3f37 100644
--- a/v3/@claude-flow/cli/agents/tester.yaml
+++ b/v3/@claude-flow/cli/agents/tester.yaml
@@ -7,4 +7,4 @@ capabilities:
- coverage
optimizations:
- parallel-execution
-createdAt: "2026-01-08T19:36:26.907Z"
+createdAt: "2026-01-08T20:52:25.959Z"
diff --git a/v3/@claude-flow/cli/package.json b/v3/@claude-flow/cli/package.json
index 53063da112..24620b2fdb 100644
--- a/v3/@claude-flow/cli/package.json
+++ b/v3/@claude-flow/cli/package.json
@@ -1,6 +1,6 @@
{
"name": "@claude-flow/cli",
- "version": "3.0.0-alpha.57",
+ "version": "3.0.0-alpha.58",
"type": "module",
"description": "CLI module - command parsing, prompts, output formatting",
"main": "dist/src/index.js",
diff --git a/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts
index 844e41281f..71a2bda3b8 100644
--- a/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts
+++ b/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts
@@ -3,10 +3,133 @@
* Provides intelligent hooks functionality via MCP protocol
*/
-import { mkdirSync, writeFileSync, existsSync } from 'fs';
+import { mkdirSync, writeFileSync, existsSync, readFileSync, statSync } from 'fs';
import { join, resolve } from 'path';
import type { MCPTool } from './types.js';
+// Memory store types and helpers
+interface MemoryEntry {
+ key: string;
+ value: unknown;
+ metadata?: Record<string, unknown>;
+ storedAt: string;
+ accessCount: number;
+ lastAccessed: string;
+}
+
+interface MemoryStore {
+ entries: Record<string, MemoryEntry>;
+ version: string;
+}
+
+const MEMORY_DIR = '.claude-flow/memory';
+const MEMORY_FILE = 'store.json';
+
+function getMemoryPath(): string {
+ return resolve(join(MEMORY_DIR, MEMORY_FILE));
+}
+
+function loadMemoryStore(): MemoryStore {
+ try {
+ const path = getMemoryPath();
+ if (existsSync(path)) {
+ const data = readFileSync(path, 'utf-8');
+ return JSON.parse(data);
+ }
+ } catch {
+ // Return empty store on error
+ }
+ return { entries: {}, version: '3.0.0' };
+}
+
+/**
+ * Get real intelligence statistics from memory store
+ */
+function getIntelligenceStatsFromMemory(): {
+ trajectories: { total: number; successful: number };
+ patterns: { learned: number; categories: Record<string, number> };
+ memory: { indexSize: number; totalAccessCount: number; memorySizeBytes: number };
+ routing: { decisions: number; avgConfidence: number };
+} {
+ const store = loadMemoryStore();
+ const entries = Object.values(store.entries);
+
+ // Count trajectories (keys starting with "trajectory-" or containing trajectory data)
+ const trajectoryEntries = entries.filter(e =>
+ e.key.includes('trajectory') ||
+ (e.metadata?.type === 'trajectory')
+ );
+ const successfulTrajectories = trajectoryEntries.filter(e =>
+ e.metadata?.success === true ||
+ (typeof e.value === 'object' && e.value !== null && (e.value as Record<string, unknown>).success === true)
+ );
+
+ // Count patterns
+ const patternEntries = entries.filter(e =>
+ e.key.includes('pattern') ||
+ e.metadata?.type === 'pattern' ||
+ e.key.startsWith('learned-')
+ );
+
+ // Categorize patterns
+ const categories: Record<string, number> = {};
+ patternEntries.forEach(e => {
+ const category = (e.metadata?.category as string) || 'general';
+ categories[category] = (categories[category] || 0) + 1;
+ });
+
+ // Count routing decisions
+ const routingEntries = entries.filter(e =>
+ e.key.includes('routing') ||
+ e.metadata?.type === 'routing-decision'
+ );
+
+ // Calculate average confidence from routing decisions
+ let totalConfidence = 0;
+ let confidenceCount = 0;
+ routingEntries.forEach(e => {
+ const confidence = e.metadata?.confidence as number;
+ if (typeof confidence === 'number') {
+ totalConfidence += confidence;
+ confidenceCount++;
+ }
+ });
+
+ // Calculate total access count
+ const totalAccessCount = entries.reduce((sum, e) => sum + (e.accessCount || 0), 0);
+
+ // Calculate memory file size
+ let memorySizeBytes = 0;
+ try {
+ const memPath = getMemoryPath();
+ if (existsSync(memPath)) {
+ memorySizeBytes = statSync(memPath).size;
+ }
+ } catch {
+ // Ignore
+ }
+
+ return {
+ trajectories: {
+ total: trajectoryEntries.length,
+ successful: successfulTrajectories.length,
+ },
+ patterns: {
+ learned: patternEntries.length,
+ categories,
+ },
+ memory: {
+ indexSize: entries.length,
+ totalAccessCount,
+ memorySizeBytes,
+ },
+ routing: {
+ decisions: routingEntries.length,
+ avgConfidence: confidenceCount > 0 ? totalConfidence / confidenceCount : 0,
+ },
+ };
+}
+
// Agent routing configuration - maps file types to recommended agents
const AGENT_PATTERNS: Record<string, string[]> = {
'.ts': ['coder', 'architect', 'tester'],
diff --git a/v3/package-lock.json b/v3/package-lock.json
index 979a8399cb..54461d5f5f 100644
--- a/v3/package-lock.json
+++ b/v3/package-lock.json
@@ -124,7 +124,7 @@
}
},
"@claude-flow/cli": {
- "version": "3.0.0-alpha.57",
+ "version": "3.0.0-alpha.58",
"dependencies": {
"@claude-flow/shared": "^3.0.0-alpha.1"
},