opencode-swarm-plugin 0.57.6 → 0.59.0

package/bin/swarm.ts

@@ -63,11 +63,12 @@ import { tmpdir } from "os";
 
 // Query & observability tools
 import {
-  executeQuery,
+  executeQueryCLI,
   executePreset,
   formatAsTable,
   formatAsCSV,
   formatAsJSON,
+  type QueryResult,
 } from "../src/query-tools.js";
 import {
   getWorkerStatus,
@@ -2831,12 +2832,27 @@ async function claudeCommand() {
     case "user-prompt":
       await claudeUserPrompt();
       break;
+    case "pre-edit":
+      await claudePreEdit();
+      break;
+    case "pre-complete":
+      await claudePreComplete();
+      break;
+    case "post-complete":
+      await claudePostComplete();
+      break;
     case "pre-compact":
       await claudePreCompact();
       break;
     case "session-end":
       await claudeSessionEnd();
       break;
+    case "track-tool":
+      await claudeTrackTool(Bun.argv[4]); // tool name is 4th arg
+      break;
+    case "compliance":
+      await claudeCompliance();
+      break;
     default:
       console.error(`Unknown subcommand: ${subcommand}`);
       showClaudeHelp();
@@ -2855,6 +2871,9 @@ Commands:
   init                Create project-local .claude/ config
   session-start       Hook: session start context (JSON output)
   user-prompt         Hook: prompt submit context (JSON output)
+  pre-edit            Hook: pre-Edit/Write reminder (hivemind check)
+  pre-complete        Hook: pre-swarm_complete checklist
+  post-complete       Hook: post-swarm_complete learnings reminder
   pre-compact         Hook: pre-compaction handler
   session-end         Hook: session cleanup
 `);
@@ -3286,6 +3305,319 @@ async function claudeSessionEnd() {
   }
 }
 
+/**
+ * Claude hook: pre-edit reminder for workers
+ *
+ * Runs BEFORE Edit/Write tool calls. Reminds worker to query hivemind first.
+ * This is a gentle nudge, not a blocker.
+ */
+async function claudePreEdit() {
+  try {
+    const input = await readHookInput<ClaudeHookInput & { tool_name?: string; tool_input?: Record<string, unknown> }>();
+
+    // Only inject reminder if this looks like a worker context
+    // (workers have initialized via swarmmail_init)
+    const projectPath = resolveClaudeProjectPath(input);
+
+    // Check if we've seen hivemind_find in this session
+    // For now, we always remind - tracking will come later
+    const contextLines: string[] = [];
+
+    contextLines.push("⚠️ **Before this edit**: Did you run `hivemind_find` to check for existing solutions?");
+    contextLines.push("If you haven't queried hivemind yet, consider doing so to avoid re-solving problems.");
+
+    writeClaudeHookOutput("PreToolUse:Edit", contextLines.join("\n"), { suppressOutput: true });
+  } catch (error) {
+    // Non-fatal - don't block the edit
+    console.error(error instanceof Error ? error.message : String(error));
+  }
+}
+
+/**
+ * Claude hook: pre-complete check for workers
+ *
+ * Runs BEFORE swarm_complete. Checks compliance with mandatory steps
+ * and warns if any were skipped.
+ */
+async function claudePreComplete() {
+  try {
+    const input = await readHookInput<ClaudeHookInput & { tool_input?: Record<string, unknown> }>();
+    const projectPath = resolveClaudeProjectPath(input);
+    const contextLines: string[] = [];
+
+    // Check session tracking markers
+    const trackingDir = join(projectPath, ".claude", ".worker-tracking");
+    const sessionId = (input as { session_id?: string }).session_id || "";
+    const sessionDir = join(trackingDir, sessionId.slice(0, 8));
+
+    const mandatoryTools = [
+      { name: "swarmmail_init", label: "Initialize coordination" },
+      { name: "hivemind_find", label: "Query past learnings" },
+    ];
+    const recommendedTools = [
+      { name: "skills_use", label: "Load relevant skills" },
+      { name: "hivemind_store", label: "Store new learnings" },
+    ];
+
+    const missing: string[] = [];
+    const skippedRecommended: string[] = [];
+
+    for (const tool of mandatoryTools) {
+      const markerPath = join(sessionDir, `${tool.name}.marker`);
+      if (!existsSync(markerPath)) {
+        missing.push(tool.label);
+      }
+    }
+
+    for (const tool of recommendedTools) {
+      const markerPath = join(sessionDir, `${tool.name}.marker`);
+      if (!existsSync(markerPath)) {
+        skippedRecommended.push(tool.label);
+      }
+    }
+
+    if (missing.length > 0) {
+      contextLines.push("⚠️ **MANDATORY STEPS SKIPPED:**");
+      for (const step of missing) {
+        contextLines.push(`  ❌ ${step}`);
+      }
+      contextLines.push("");
+      contextLines.push("These steps are critical for swarm coordination.");
+      contextLines.push("Consider running `hivemind_find` before future completions.");
+    }
+
+    if (skippedRecommended.length > 0 && missing.length === 0) {
+      contextLines.push("📝 **Recommended steps not observed:**");
+      for (const step of skippedRecommended) {
+        contextLines.push(`  - ${step}`);
+      }
+    }
+
+    if (missing.length === 0 && skippedRecommended.length === 0) {
+      contextLines.push("✅ **All mandatory and recommended steps completed!**");
+    }
+
+    // Emit compliance event for analytics
+    try {
+      const swarmMail = await getSwarmMailLibSQL(projectPath);
+      const db = await swarmMail.getDatabase(projectPath);
+
+      await db.execute({
+        sql: `INSERT INTO swarm_events (event_type, project_path, agent_name, epic_id, bead_id, payload, created_at)
+              VALUES (?, ?, ?, ?, ?, ?, datetime('now'))`,
+        args: [
+          "worker_compliance",
+          projectPath,
+          "worker",
+          "",
+          "",
+          JSON.stringify({
+            session_id: sessionId,
+            mandatory_skipped: missing.length,
+            recommended_skipped: skippedRecommended.length,
+            score: Math.round(((mandatoryTools.length - missing.length) / mandatoryTools.length) * 100),
+          }),
+        ],
+      });
+    } catch {
+      // Non-fatal
+    }
+
+    if (contextLines.length > 0) {
+      writeClaudeHookOutput("PreToolUse:swarm_complete", contextLines.join("\n"), { suppressOutput: missing.length === 0 });
+    }
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+  }
+}
+
+/**
+ * Claude hook: post-complete reminder for workers
+ *
+ * Runs AFTER swarm_complete. Reminds to store learnings if any were discovered.
+ */
+async function claudePostComplete() {
+  try {
+    const input = await readHookInput<ClaudeHookInput & { tool_output?: string }>();
+    const contextLines: string[] = [];
+
+    contextLines.push("✅ Task completed. If you discovered anything valuable during this work:");
+    contextLines.push("```");
+    contextLines.push("hivemind_store(");
+    contextLines.push('  information="<what you learned, WHY it matters>",');
+    contextLines.push('  tags="<domain, pattern-type>"');
+    contextLines.push(")");
+    contextLines.push("```");
+    contextLines.push("**The swarm's collective intelligence grows when agents share learnings.**");
+
+    writeClaudeHookOutput("PostToolUse:swarm_complete", contextLines.join("\n"), { suppressOutput: true });
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+  }
+}
+
+/**
+ * Track when a mandatory tool is called.
+ *
+ * Creates a session-specific marker file that records tool usage.
+ * These markers are checked at swarm_complete to calculate compliance.
+ */
+async function claudeTrackTool(toolName: string) {
+  if (!toolName) return;
+
+  try {
+    const input = await readHookInput<ClaudeHookInput>();
+    const projectPath = resolveClaudeProjectPath(input);
+
+    // Get or create session tracking directory
+    const trackingDir = join(projectPath, ".claude", ".worker-tracking");
+    const sessionId = (input as { session_id?: string }).session_id || `unknown-${Date.now()}`;
+    const sessionDir = join(trackingDir, sessionId.slice(0, 8)); // Use first 8 chars of session ID
+
+    if (!existsSync(sessionDir)) {
+      mkdirSync(sessionDir, { recursive: true });
+    }
+
+    // Write marker file for this tool
+    const markerPath = join(sessionDir, `${toolName}.marker`);
+    writeFileSync(markerPath, new Date().toISOString());
+
+    // Also emit an event for long-term analytics (non-blocking)
+    try {
+      const swarmMail = await getSwarmMailLibSQL(projectPath);
+      const db = await swarmMail.getDatabase(projectPath);
+
+      await db.execute({
+        sql: `INSERT INTO swarm_events (event_type, project_path, agent_name, epic_id, bead_id, payload, created_at)
+              VALUES (?, ?, ?, ?, ?, ?, datetime('now'))`,
+        args: [
+          "worker_tool_call",
+          projectPath,
+          "worker", // We don't have agent name in hook context
+          "",
+          "",
+          JSON.stringify({ tool: toolName, session_id: sessionId }),
+        ],
+      });
+    } catch {
+      // Non-fatal - tracking is best-effort
+    }
+  } catch (error) {
+    // Silent failure - don't interrupt the tool call
+    console.error(`[track-tool] ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/**
+ * Check worker compliance - which mandatory tools were called.
+ *
+ * Returns compliance data based on session tracking markers.
+ */
+async function claudeCompliance() {
+  try {
+    const input = await readHookInput<ClaudeHookInput>();
+    const projectPath = resolveClaudeProjectPath(input);
+
+    const trackingDir = join(projectPath, ".claude", ".worker-tracking");
+    const sessionId = (input as { session_id?: string }).session_id || "";
+    const sessionDir = join(trackingDir, sessionId.slice(0, 8));
+
+    const mandatoryTools = ["swarmmail_init", "hivemind_find", "skills_use"];
+    const recommendedTools = ["hivemind_store"];
+
+    const compliance: Record<string, boolean> = {};
+
+    for (const tool of [...mandatoryTools, ...recommendedTools]) {
+      const markerPath = join(sessionDir, `${tool}.marker`);
+      compliance[tool] = existsSync(markerPath);
+    }
+
+    const mandatoryCount = mandatoryTools.filter(t => compliance[t]).length;
+    const score = Math.round((mandatoryCount / mandatoryTools.length) * 100);
+
+    console.log(JSON.stringify({
+      session_id: sessionId,
+      compliance,
+      mandatory_score: score,
+      mandatory_met: mandatoryCount,
+      mandatory_total: mandatoryTools.length,
+      stored_learnings: compliance.hivemind_store,
+    }));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+  }
+}
+
+/**
+ * Query worker compliance stats across all sessions.
+ */
+async function showWorkerCompliance() {
+  const projectPath = process.cwd();
+
+  try {
+    // Use shared executeQuery (handles DB connection internally)
+    const toolUsageSql = `SELECT
+      json_extract(payload, '$.tool') as tool,
+      COUNT(*) as count,
+      COUNT(DISTINCT json_extract(payload, '$.session_id')) as sessions
+    FROM swarm_events
+    WHERE event_type = 'worker_tool_call'
+      AND created_at > datetime('now', '-7 days')
+    GROUP BY tool
+    ORDER BY count DESC`;
+
+    const toolResult = await executeQueryCLI(projectPath, toolUsageSql);
+    const rows = toolResult.rows;
+
+    console.log(yellow(BANNER));
+    console.log(cyan("\n📊 Worker Tool Usage (Last 7 Days)\n"));
+
+    if (rows.length === 0) {
+      console.log(dim("No worker tool usage data found."));
+      console.log(dim("Data is collected when workers run with the Claude Code plugin."));
+      return;
+    }
+
+    console.log(dim("Tool                    Calls   Sessions"));
+    console.log(dim("─".repeat(45)));
+
+    for (const row of rows) {
+      const tool = String(row.tool).padEnd(22);
+      const count = String(row.count).padStart(6);
+      const sessions = String(row.sessions).padStart(8);
+      console.log(`${tool} ${count} ${sessions}`);
+    }
+
+    // Calculate compliance rate
+    const hivemindFinds = rows.find(r => r.tool === "hivemind_find");
+    const completesSql = `SELECT COUNT(*) as count FROM swarm_events
+      WHERE event_type = 'worker_completed'
+        AND created_at > datetime('now', '-7 days')`;
+    const completesResult = await executeQueryCLI(projectPath, completesSql);
+
+    const completes = Number(completesResult.rows[0]?.count || 0);
+    const finds = Number(hivemindFinds?.count || 0);
+
+    if (completes > 0) {
+      const rate = Math.round((Math.min(finds, completes) / completes) * 100);
+      console.log(dim("\n─".repeat(45)));
+      console.log(`\n${green("Hivemind compliance rate:")} ${rate}% (${finds} queries / ${completes} completions)`);
+    }
+
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    if (msg.includes("no such table")) {
+      console.log(yellow(BANNER));
+      console.log(cyan("\n📊 Worker Tool Usage\n"));
+      console.log(dim("No tracking data yet."));
+      console.log(dim("Compliance tracking starts when workers run with the Claude Code plugin hooks."));
+      console.log(dim("\nThe swarm_events table will be created on first tracked tool call."));
+    } else {
+      console.error("Error fetching compliance data:", msg);
+    }
+  }
+}
+
 async function init() {
   p.intro("swarm init v" + VERSION);
 
@@ -3633,16 +3965,16 @@ async function query() {
   const projectPath = process.cwd();
 
   try {
-    let rows: any[];
+    let result: QueryResult;
 
     if (parsed.preset) {
       // Execute preset query
       p.log.step(`Executing preset: ${parsed.preset}`);
-      rows = await executePreset(projectPath, parsed.preset);
+      result = await executePreset(projectPath, parsed.preset);
     } else if (parsed.query) {
       // Execute custom SQL
       p.log.step("Executing custom SQL");
-      rows = await executeQuery(projectPath, parsed.query);
+      result = await executeQueryCLI(projectPath, parsed.query);
     } else {
       p.log.error("No query specified. Use --sql or --preset");
       p.outro("Aborted");
@@ -3653,14 +3985,14 @@ async function query() {
     let output: string;
     switch (parsed.format) {
       case "csv":
-        output = formatAsCSV(rows);
+        output = formatAsCSV(result);
         break;
       case "json":
-        output = formatAsJSON(rows);
+        output = formatAsJSON(result);
         break;
       case "table":
       default:
-        output = formatAsTable(rows);
+        output = formatAsTable(result);
         break;
     }
 
@@ -3668,7 +4000,7 @@ async function query() {
     console.log(output);
     console.log();
 
-    p.outro(`Found ${rows.length} result(s)`);
+    p.outro(`Found ${result.rowCount} result(s)`);
   } catch (error) {
     p.log.error("Query failed");
     p.log.message(error instanceof Error ? error.message : String(error));
@@ -4032,6 +4364,7 @@ ${cyan("Commands:")}
   swarm eval      Eval-driven development commands
   swarm query     SQL analytics with presets (--sql, --preset, --format)
   swarm dashboard Live terminal UI with worker status (--epic, --refresh)
+  swarm compliance Worker tool usage compliance stats (hivemind, skills, etc)
   swarm replay    Event replay with timing (--speed, --type, --agent, --since, --until)
   swarm export    Export events (--format otlp/csv/json, --epic, --output)
   swarm tree      Visualize cell hierarchy as ASCII tree (--status, --epic, --json)
@@ -4118,6 +4451,7 @@ ${cyan("Observability Commands:")}
   swarm export --format csv            Export as CSV
   swarm export --epic <id>             Export specific epic only
   swarm export --output <file>         Write to file instead of stdout
+  swarm compliance                     Show worker tool usage compliance stats
   swarm tree                           Show all cells as tree
   swarm tree --status open             Show only open cells
   swarm tree --epic <id>               Show specific epic subtree
@@ -4142,6 +4476,11 @@ ${cyan("Claude Code:")}
   swarm claude init                 Create project-local .claude config
   swarm claude session-start        Hook: session start context
   swarm claude user-prompt          Hook: prompt submit context
+  swarm claude pre-edit             Hook: pre-Edit/Write (hivemind reminder)
+  swarm claude pre-complete         Hook: pre-swarm_complete (compliance check)
+  swarm claude post-complete        Hook: post-swarm_complete (store learnings)
+  swarm claude track-tool <name>    Hook: track mandatory tool usage
+  swarm claude compliance           Hook: show session compliance data
   swarm claude pre-compact          Hook: pre-compaction handler
   swarm claude session-end          Hook: session cleanup
 
@@ -7449,6 +7788,9 @@ switch (command) {
   case "dashboard":
     await dashboard();
     break;
+  case "compliance":
+    await showWorkerCompliance();
+    break;
   case "replay":
     await replay();
     break;

package/claude-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "swarm",
   "description": "Multi-agent task decomposition and coordination for Claude Code",
-  "version": "0.57.5",
+  "version": "0.58.3",
   "author": {
     "name": "Joel Hooks"
   },

package/claude-plugin/README.md

@@ -0,0 +1,187 @@
+# Swarm Plugin for Claude Code
+
+Multi-agent task decomposition and coordination for Claude Code.
+
+## Prerequisites
+
+The swarm CLI must be installed globally:
+
+```bash
+npm install -g opencode-swarm-plugin
+# or
+bun add -g opencode-swarm-plugin
+```
+
+Verify installation:
+
+```bash
+swarm version
+```
+
+## Installation
+
+### Via Marketplace (Recommended)
+
+Add the marketplace to your Claude Code settings, then install:
+
+```bash
+claude /plugin install swarm
+```
+
+### Via Plugin Directory (Development)
+
+```bash
+claude --plugin-dir /path/to/opencode-swarm-plugin/packages/opencode-swarm-plugin/claude-plugin
+```
+
+## Usage
+
+### Start a Swarm
+
+Use the `/swarm:swarm` command to decompose a task into parallel subtasks:
+
+```
+/swarm:swarm Add user authentication with OAuth support
+```
+
+The coordinator will:
+1. Query hivemind for past learnings
+2. Clarify scope if needed
+3. Decompose into parallel subtasks
+4. Spawn workers for each subtask
+5. Review completed work
+6. Store learnings for future swarms
+
+### Other Commands
+
+| Command | Description |
+|---------|-------------|
+| `/swarm:swarm <task>` | Decompose and execute a multi-agent task |
+| `/swarm:status` | Check worker progress, inbox, reservations |
+| `/swarm:inbox` | Review inter-agent messages |
+| `/swarm:hive` | Query and manage tasks (cells) |
+| `/swarm:handoff` | End session, release locks, sync state |
+
+### Skills (Auto-Invoked)
+
+The plugin includes skills that Claude uses automatically:
+
+- **swarm-coordination** - Multi-agent workflow guidance
+- **always-on-guidance** - Model-specific defaults and best practices
+
+## Available Tools
+
+### Coordinator Tools
+
+| Tool | Purpose |
+|------|---------|
+| `hivemind_find` | Query past learnings before decomposing |
+| `hivemind_store` | Store discovered patterns |
+| `swarm_decompose` | Break task into subtasks |
+| `swarm_spawn_subtask` | Launch worker for subtask |
+| `swarm_spawn_researcher` | Launch read-only researcher |
+| `swarm_review` | Review worker output |
+| `swarm_status` | Check epic progress |
+| `hive_create_epic` | Create epic with subtasks |
+| `hive_query` | Query task database |
+| `swarmmail_*` | Inter-agent messaging |
+
+### Worker Tools
+
+| Tool | Purpose |
+|------|---------|
+| `hivemind_find` | Query learnings before starting |
+| `hivemind_store` | Store what you learn |
+| `swarm_progress` | Report progress (25/50/75%) |
+| `swarm_checkpoint` | Save context before risky ops |
+| `swarm_complete` | Signal task completion |
+| `hive_update` | Update task status |
+| `hive_close` | Close completed task |
+| `swarmmail_reserve` | Reserve files exclusively |
+| `swarmmail_send` | Message other agents |
+
+## Architecture
+
+```
+Coordinator (Opus)
+├── Queries hivemind for past learnings
+├── Decomposes task into subtasks
+├── Spawns workers (Sonnet)
+├── Reviews each worker before spawning next
+└── Stores coordination learnings
+
+Workers (Sonnet)
+├── Query hivemind before starting
+├── Reserve files to prevent conflicts
+├── Execute scoped subtask
+├── Report progress at 25/50/75%
+└── Store domain learnings
+
+Researchers (Opus, read-only)
+├── Fetch documentation
+├── Analyze dependencies
+└── Store findings in hivemind
+```
+
+## Troubleshooting
+
+### MCP Server Not Connecting
+
+Ensure swarm is installed globally and in your PATH:
+
+```bash
+which swarm
+swarm mcp-serve  # Should start without errors
+```
+
+### Tools Not Available
+
+Check that the MCP server is running:
+
+```bash
+claude mcp list
+```
+
+The `swarm-tools` server should show as connected.
+
+### File Conflicts
+
+If multiple agents are editing the same file, use file reservations:
+
+```
+swarmmail_reserve(paths: ["src/**/*.ts"], exclusive: true)
+```
+
+### Context Exhaustion
+
+Use checkpoints before large operations:
+
+```
+swarm_checkpoint(reason: "Before refactor")
+```
+
+## Development
+
+### Testing Locally
+
+```bash
+# From the plugin directory
+claude --plugin-dir .
+```
+
+### Building
+
+```bash
+cd packages/opencode-swarm-plugin
+bun run build
+```
+
+### Running Tests
+
+```bash
+bun test
+```
+
+## License
+
+MIT

package/claude-plugin/agents/worker.md

@@ -5,6 +5,7 @@ model: sonnet
 skills:
   - always-on-guidance
   - swarm-coordination
+  - swarm-cli
   - testing-patterns
   - system-design
 tools: