claude-flow 1.0.21 → 1.0.22

package/README.md

@@ -138,6 +138,8 @@ Comprehensive documentation is available to help you get the most out of Claude-
 - **[Terminal Management](./docs/08-terminal-management.md)** - Terminal pooling and sessions
 - **[Troubleshooting](./docs/09-troubleshooting.md)** - Common issues and solutions
 - **[Advanced Usage](./docs/10-advanced-usage.md)** - Power user features
+- **[Claude Spawning](./docs/11-claude-spawning.md)** - Spawning Claude instances
+- **[Swarm Mode](./docs/12-swarm.md)** - Self-orchestrating agent swarms 🐝
 - **[CLI Reference](./docs/cli-reference.md)** - Complete command documentation
 
 ## 💡 **Quick Start Guide**
@@ -189,7 +191,33 @@ npx claude-flow claude spawn "fix payment bug" --tools "View,Edit,Bash" --no-per
 npx claude-flow claude batch examples/claude-workflow.json --dry-run
 ```
 
-### 6. **Monitor System Status**
+### 6. **Claude Swarm Mode** 🐝 🆕
+```bash
+# Create self-orchestrating agent swarms
+npx claude-flow swarm "Build a complete e-commerce platform"
+
+# Research-focused swarm
+npx claude-flow swarm "Research cloud architecture best practices" \
+  --strategy research --research --max-agents 8
+
+# Development swarm with review
+npx claude-flow swarm "Refactor authentication system" \
+  --strategy development --review --parallel
+
+# Complex project with coordinator
+npx claude-flow swarm "Migrate monolithic app to microservices" \
+  --coordinator --max-depth 4 --timeout 120
+
+# Preview swarm configuration
+npx claude-flow swarm "Create mobile app" --dry-run --verbose
+
+# Run with visual monitoring (recommended for visibility)
+./bin/claude-flow-swarm-monitor "Build REST API" --strategy development
+```
+
+**Note**: Swarm mode currently spawns a single orchestrator that simulates multiple agents. For true multi-instance spawning, see [SWARM_VISIBILITY.md](./SWARM_VISIBILITY.md).
+
+### 7. **Monitor System Status**
 ```bash
 # Check system health
 npx claude-flow status
@@ -477,7 +505,7 @@ claude-flow task workflow example-workflow.json
 ## Development
 
 ### Prerequisites
-- Deno 1.38+ or Node.js 16+
+- Deno 1.38+ or Node.js 16+ (Install Deno: https://deno.land/#installation)
 - Git
 
 ### Setup

package/bin/claude-flow-swarm

@@ -0,0 +1,19 @@
+#!/bin/bash
+# Claude-Flow Swarm Mode Wrapper
+# This script wraps the swarm demo to work with the installed Deno
+
+# Find deno in the path
+DENO_PATH=$(which deno 2>/dev/null || echo "/home/codespace/.deno/bin/deno")
+
+if [ ! -x "$DENO_PATH" ]; then
+    echo "Error: Deno is not installed or not in PATH"
+    echo "Please install Deno first: https://deno.land/#installation"
+    exit 1
+fi
+
+# Get the directory of this script
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+SWARM_DEMO="$SCRIPT_DIR/../swarm-demo.ts"
+
+# Run the swarm demo with all arguments
+exec "$DENO_PATH" run --allow-all "$SWARM_DEMO" "$@"

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "claude-flow",
-  "version": "1.0.21",
+  "version": "1.0.22",
   "description": "Advanced AI agent orchestration system for Claude Code",
   "main": "src/cli/main.ts",
   "bin": {
-    "claude-flow": "./bin/claude-flow"
+    "claude-flow": "./bin/claude-flow",
+    "claude-flow-swarm": "./bin/claude-flow-swarm"
   },
   "scripts": {
     "postinstall": "node scripts/install.js",
@@ -36,7 +37,9 @@
   },
   "files": [
     "bin/claude-flow",
+    "bin/claude-flow-swarm",
     "src/",
+    "swarm-demo.ts",
     "scripts/install.js",
     "README.md",
     "LICENSE",

package/src/cli/cli-core.ts

@@ -86,7 +86,7 @@ class CLI {
       string: this.getStringFlags(),
       alias: this.getAliases(),
       default: this.getDefaults(),
-      stopEarly: true,
+      stopEarly: false,
       unknown: () => true,
     });
 

package/src/cli/commands/index.ts

@@ -7,6 +7,7 @@ import { MemoryManager } from "../../memory/manager.ts";
 import { EventBus } from "../../core/event-bus.ts";
 import { Logger } from "../../core/logger.ts";
 import { JsonPersistenceManager } from "../../core/json-persistence.ts";
+import { swarmAction } from "./swarm.ts";
 
 let orchestrator: Orchestrator | null = null;
 let configManager: ConfigManager | null = null;
@@ -993,6 +994,84 @@ export function setupCommands(cli: CLI): void {
     },
   });
 
+  // Swarm command
+  cli.command({
+    name: "swarm",
+    description: "Create self-orchestrating Claude agent swarms",
+    options: [
+      {
+        name: "strategy",
+        short: "s",
+        description: "Orchestration strategy (auto, research, development, analysis)",
+        type: "string",
+        default: "auto",
+      },
+      {
+        name: "max-agents",
+        description: "Maximum number of agents to spawn",
+        type: "number",
+        default: 5,
+      },
+      {
+        name: "max-depth",
+        description: "Maximum delegation depth",
+        type: "number",
+        default: 3,
+      },
+      {
+        name: "research",
+        description: "Enable research capabilities for all agents",
+        type: "boolean",
+      },
+      {
+        name: "parallel",
+        description: "Enable parallel execution",
+        type: "boolean",
+      },
+      {
+        name: "memory-namespace",
+        description: "Shared memory namespace",
+        type: "string",
+        default: "swarm",
+      },
+      {
+        name: "timeout",
+        description: "Swarm timeout in minutes",
+        type: "number",
+        default: 60,
+      },
+      {
+        name: "review",
+        description: "Enable peer review between agents",
+        type: "boolean",
+      },
+      {
+        name: "coordinator",
+        description: "Spawn dedicated coordinator agent",
+        type: "boolean",
+      },
+      {
+        name: "config",
+        short: "c",
+        description: "MCP config file",
+        type: "string",
+      },
+      {
+        name: "verbose",
+        short: "v",
+        description: "Enable verbose output",
+        type: "boolean",
+      },
+      {
+        name: "dry-run",
+        short: "d",
+        description: "Preview swarm configuration",
+        type: "boolean",
+      },
+    ],
+    action: swarmAction,
+  });
+
   // Help command
   cli.command({
     name: "help",
@@ -1027,6 +1106,34 @@ export function setupCommands(cli: CLI): void {
         console.log(`  ${blue("claude-flow claude batch")} workflow.json --dry-run`);
         console.log();
         console.log("For more information, see: https://github.com/ruvnet/claude-code-flow/docs/11-claude-spawning.md");
+      } else if (command === "swarm") {
+        console.log(bold(blue("Claude Swarm Mode")));
+        console.log();
+        console.log("Create self-orchestrating Claude agent swarms to tackle complex objectives.");
+        console.log();
+        console.log(bold("Usage:"));
+        console.log("  claude-flow swarm <objective> [options]");
+        console.log();
+        console.log(bold("Options:"));
+        console.log("  -s, --strategy <s>         Orchestration strategy (auto, research, development, analysis)");
+        console.log("  --max-agents <n>           Maximum number of agents (default: 5)");
+        console.log("  --max-depth <n>            Maximum delegation depth (default: 3)");
+        console.log("  --research                 Enable research capabilities for all agents");
+        console.log("  --parallel                 Enable parallel execution");
+        console.log("  --memory-namespace <ns>    Shared memory namespace (default: swarm)");
+        console.log("  --timeout <minutes>        Swarm timeout in minutes (default: 60)");
+        console.log("  --review                   Enable peer review between agents");
+        console.log("  --coordinator              Spawn dedicated coordinator agent");
+        console.log("  -c, --config <file>        MCP config file");
+        console.log("  -v, --verbose              Enable verbose output");
+        console.log("  -d, --dry-run              Preview swarm configuration");
+        console.log();
+        console.log(bold("Examples:"));
+        console.log(`  ${blue("claude-flow swarm")} "Build a REST API"`);
+        console.log(`  ${blue("claude-flow swarm")} "Research cloud architecture" --strategy research --research`);
+        console.log(`  ${blue("claude-flow swarm")} "Migrate app to microservices" --coordinator --review`);
+        console.log();
+        console.log("For more information, see: https://github.com/ruvnet/claude-code-flow/docs/12-swarm.md");
       } else {
         // Show general help
         cli.showHelp();

package/src/cli/commands/swarm-spawn.ts

@@ -0,0 +1,353 @@
+/**
+ * Swarm agent spawning utilities
+ */
+
+import { generateId } from '../../utils/helpers.ts';
+import { info, success, error, warning } from '../cli-core.ts';
+
+export interface SwarmAgent {
+  id: string;
+  type: 'researcher' | 'developer' | 'analyst' | 'reviewer' | 'coordinator';
+  name: string;
+  task: string;
+  parentId?: string;
+  terminalId?: string;
+  status: 'pending' | 'active' | 'completed' | 'failed';
+}
+
+export interface SwarmState {
+  swarmId: string;
+  objective: string;
+  agents: Map<string, SwarmAgent>;
+  tasks: Map<string, any>;
+  startTime: number;
+}
+
+// Global swarm state registry
+const swarmStates = new Map<string, SwarmState>();
+
+/**
+ * Initialize a new swarm
+ */
+export function initializeSwarm(swarmId: string, objective: string): SwarmState {
+  const state: SwarmState = {
+    swarmId,
+    objective,
+    agents: new Map(),
+    tasks: new Map(),
+    startTime: Date.now(),
+  };
+  
+  swarmStates.set(swarmId, state);
+  return state;
+}
+
+/**
+ * Get swarm state
+ */
+export function getSwarmState(swarmId: string): SwarmState | undefined {
+  return swarmStates.get(swarmId);
+}
+
+/**
+ * Spawn a new agent in a terminal
+ */
+export async function spawnSwarmAgent(
+  swarmId: string,
+  agentType: SwarmAgent['type'],
+  task: string,
+  parentId?: string
+): Promise<SwarmAgent> {
+  const state = getSwarmState(swarmId);
+  if (!state) {
+    throw new Error(`Swarm ${swarmId} not found`);
+  }
+  
+  const agentId = generateId(`${agentType}-agent`);
+  const agent: SwarmAgent = {
+    id: agentId,
+    type: agentType,
+    name: `${agentType.charAt(0).toUpperCase() + agentType.slice(1)} Agent ${agentId.slice(-6)}`,
+    task,
+    parentId,
+    status: 'pending',
+  };
+  
+  state.agents.set(agentId, agent);
+  
+  info(`🤖 Spawning ${agent.name}...`);
+  
+  try {
+    // Create agent prompt
+    const agentPrompt = buildAgentPrompt(agent, state);
+    
+    // Check if we're in VS Code
+    if (Deno.env.get('TERM_PROGRAM') === 'vscode') {
+      await spawnVSCodeAgent(swarmId, agent, agentPrompt);
+    } else {
+      await spawnNativeAgent(swarmId, agent, agentPrompt);
+    }
+    
+    agent.status = 'active';
+    success(`✅ ${agent.name} spawned successfully`);
+    
+  } catch (err) {
+    agent.status = 'failed';
+    error(`Failed to spawn ${agent.name}: ${(err as Error).message}`);
+  }
+  
+  return agent;
+}
+
+/**
+ * Build agent-specific prompt
+ */
+function buildAgentPrompt(agent: SwarmAgent, state: SwarmState): string {
+  const roleDescriptions = {
+    researcher: 'gather information, analyze sources, and provide insights',
+    developer: 'implement code, create features, and fix bugs',
+    analyst: 'analyze data, identify patterns, and provide recommendations',
+    reviewer: 'review code and outputs, ensure quality, and provide feedback',
+    coordinator: 'coordinate subtasks, manage dependencies, and track progress',
+  };
+  
+  return `
+# Claude Swarm Agent Task
+
+You are a **${agent.name}** in a collaborative swarm working on:
+**${state.objective}**
+
+## Your Role:
+As a ${agent.type}, your primary responsibility is to ${roleDescriptions[agent.type]}.
+
+## Your Specific Task:
+${agent.task}
+
+## Swarm Context:
+- Swarm ID: ${state.swarmId}
+- Parent Agent: ${agent.parentId || 'Master Orchestrator'}
+- Memory Namespace: swarm-${state.swarmId}
+
+## Collaboration Guidelines:
+1. Store all discoveries and outputs in the shared memory namespace
+2. Check memory for existing work before starting new tasks
+3. Coordinate with other agents via memory updates
+4. Report progress regularly
+5. Request help or spawn sub-agents if needed
+
+## Available Commands:
+- \`claude-flow memory store <key> <value>\` - Store findings
+- \`claude-flow memory retrieve <key>\` - Get shared data
+- \`claude-flow task create <type> "<description>"\` - Create subtasks
+- \`claude-flow agent spawn <type> --task "<task>"\` - Spawn sub-agents
+
+## Output Format:
+Provide regular status updates:
+\`\`\`
+[AGENT STATUS]
+- Agent: ${agent.id}
+- Progress: <percentage>
+- Current Activity: <description>
+- Findings: <summary>
+\`\`\`
+
+Begin working on your task now.
+`;
+}
+
+/**
+ * Spawn agent in VS Code terminal
+ */
+async function spawnVSCodeAgent(swarmId: string, agent: SwarmAgent, prompt: string): Promise<void> {
+  // Write prompt to temp file
+  const tempDir = await Deno.makeTempDir();
+  const promptFile = `${tempDir}/agent-${agent.id}-prompt.txt`;
+  await Deno.writeTextFile(promptFile, prompt);
+  
+  // Create agent script
+  const scriptContent = `#!/bin/bash
+# Claude Swarm Agent: ${agent.name}
+# Task: ${agent.task}
+
+export CLAUDE_SWARM_ID="${swarmId}"
+export CLAUDE_SWARM_AGENT_ID="${agent.id}"
+export CLAUDE_SWARM_AGENT_TYPE="${agent.type}"
+export CLAUDE_SWARM_MEMORY_NS="swarm-${swarmId}"
+
+echo "🤖 ${agent.name} Starting..."
+echo "📋 Task: ${agent.task}"
+echo ""
+
+# Run Claude with the agent prompt
+claude "$(cat "${promptFile}")" \\
+  --allowedTools View,Edit,Replace,GlobTool,GrepTool,LS,Bash,WebFetchTool \\
+  --verbose
+
+echo ""
+echo "✅ Agent task completed"
+`;
+
+  const scriptFile = `${tempDir}/agent-${agent.id}-run.sh`;
+  await Deno.writeTextFile(scriptFile, scriptContent);
+  await Deno.chmod(scriptFile, 0o755);
+  
+  // Use AppleScript to create new terminal tab in VS Code
+  if (Deno.build.os === 'darwin') {
+    // macOS: Use AppleScript to simulate keyboard shortcut
+    const appleScript = `
+tell application "Visual Studio Code"
+  activate
+end tell
+delay 0.5
+tell application "System Events"
+  keystroke "\`" using {control down, shift down}
+end tell
+delay 0.5
+tell application "System Events"
+  keystroke "${scriptFile}"
+  key code 36
+end tell
+`;
+    
+    const osascriptCommand = new Deno.Command('osascript', {
+      args: ['-e', appleScript],
+    });
+    
+    await osascriptCommand.output();
+  } else {
+    // For other platforms, fall back to creating a tasks.json file
+    await createVSCodeTask(swarmId, agent, scriptFile);
+  }
+  
+  // Clean up after delay
+  setTimeout(async () => {
+    try {
+      await Deno.remove(tempDir, { recursive: true });
+    } catch {}
+  }, 60000);
+}
+
+/**
+ * Create VS Code task for agent
+ */
+async function createVSCodeTask(swarmId: string, agent: SwarmAgent, scriptFile: string): Promise<void> {
+  const tasksDir = '.vscode';
+  const tasksFile = `${tasksDir}/tasks.json`;
+  
+  // Ensure .vscode directory exists
+  await Deno.mkdir(tasksDir, { recursive: true });
+  
+  // Read existing tasks or create new
+  let tasks: any = {
+    version: "2.0.0",
+    tasks: []
+  };
+  
+  try {
+    const existing = await Deno.readTextFile(tasksFile);
+    tasks = JSON.parse(existing);
+  } catch {}
+  
+  // Add new task for agent
+  const agentTask = {
+    label: `Swarm Agent: ${agent.name}`,
+    type: "shell",
+    command: scriptFile,
+    presentation: {
+      echo: true,
+      reveal: "always",
+      focus: false,
+      panel: "new",
+      showReuseMessage: false,
+      clear: false
+    },
+    problemMatcher: [],
+    isBackground: true,
+    runOptions: {
+      runOn: "default"
+    }
+  };
+  
+  tasks.tasks.push(agentTask);
+  
+  // Write updated tasks
+  await Deno.writeTextFile(tasksFile, JSON.stringify(tasks, null, 2));
+  
+  // Execute the task
+  const runTaskCommand = new Deno.Command('code', {
+    args: ['--command', `workbench.action.tasks.runTask`, '--', `Swarm Agent: ${agent.name}`],
+  });
+  
+  await runTaskCommand.output();
+}
+
+/**
+ * Spawn agent in native terminal
+ */
+async function spawnNativeAgent(swarmId: string, agent: SwarmAgent, prompt: string): Promise<void> {
+  // For native terminals, we'll use the system's terminal emulator
+  const terminalCommands = {
+    darwin: ['osascript', '-e', `tell application "Terminal" to do script "claude '${prompt.replace(/'/g, "'\\''")}'"`],
+    linux: ['gnome-terminal', '--', 'claude', prompt],
+    windows: ['cmd', '/c', 'start', 'claude', prompt],
+  };
+  
+  const platform = Deno.build.os;
+  const command = terminalCommands[platform as keyof typeof terminalCommands];
+  
+  if (!command) {
+    throw new Error(`Unsupported platform: ${platform}`);
+  }
+  
+  const process = new Deno.Command(command[0], {
+    args: command.slice(1),
+  });
+  
+  await process.output();
+}
+
+/**
+ * Monitor swarm progress
+ */
+export async function monitorSwarm(swarmId: string): Promise<void> {
+  const state = getSwarmState(swarmId);
+  if (!state) {
+    error(`Swarm ${swarmId} not found`);
+    return;
+  }
+  
+  console.log('\n📊 Swarm Status Monitor');
+  console.log('='.repeat(50));
+  
+  const updateInterval = setInterval(() => {
+    const runtime = Math.floor((Date.now() - state.startTime) / 1000);
+    const activeAgents = Array.from(state.agents.values()).filter(a => a.status === 'active').length;
+    const completedAgents = Array.from(state.agents.values()).filter(a => a.status === 'completed').length;
+    
+    console.clear();
+    console.log(`🐝 Swarm ${swarmId}`);
+    console.log(`📋 Objective: ${state.objective}`);
+    console.log(`⏱️  Runtime: ${runtime}s`);
+    console.log(`🤖 Agents: ${activeAgents} active, ${completedAgents} completed`);
+    console.log('\nAgent Status:');
+    
+    for (const agent of state.agents.values()) {
+      const statusEmoji = {
+        pending: '⏳',
+        active: '🟢',
+        completed: '✅',
+        failed: '❌',
+      };
+      
+      console.log(`  ${statusEmoji[agent.status]} ${agent.name}: ${agent.task.substring(0, 50)}...`);
+    }
+    
+  }, 2000);
+  
+  // Stop monitoring after timeout or manual interrupt
+  process.on('SIGINT', () => {
+    clearInterval(updateInterval);
+    console.log('\n\n👋 Swarm monitoring stopped');
+    process.exit(0);
+  });
+}