claude-code-swarm 0.3.7 → 0.3.8

package/.claude/settings.json

@@ -0,0 +1 @@
+{ "attribution": { "commit": "", "pr": "" } }

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "Launch Claude Code with swarmkit capabilities, including team orchestration, MAP observability, and session tracking.",
   "owner": {
     "name": "alexngai"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-code-swarm",
   "description": "Spin up Claude Code agent teams from openteams YAML topologies with optional MAP (Multi-Agent Protocol) observability and coordination. Provides hooks for session lifecycle, agent spawn/complete tracking, and a /swarm skill to launch team configurations.",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "author": {
     "name": "alexngai"
   },

package/CLAUDE.md

@@ -25,6 +25,7 @@ claude-code-swarm/
 ├── src/                          # Core logic modules
 │   ├── index.mjs                 # Barrel re-export of public API
 │   ├── config.mjs                # Config parsing + defaults
+│   ├── log.mjs                   # Structured leveled logging (JSON Lines + stderr)
 │   ├── paths.mjs                 # Path constants + ensureSwarmDir/ensureMapDir/teamDir
 │   ├── roles.mjs                 # Role reading, matching, writing roles.json
 │   ├── inbox.mjs                 # Inbox read/clear/format/write
@@ -110,6 +111,7 @@ MAP options:
 - `scope` — MAP scope name (default: `swarm:<template>`)
 - `systemId` — System identifier for federation (default: `system-claude-swarm`)
 - `sidecar` — `"session"` (starts/stops with session, default) or `"persistent"` (user-managed)
+- `reconnectIntervalMs` — Interval in ms for slow reconnection loop after SDK retries are exhausted (default: `60000`)
 - `auth.token` — Authentication token appended as a query parameter to the server URL
 - `auth.param` — Query parameter name for the token (default: `token`)
 
@@ -224,6 +226,41 @@ Skill-tree options:
 - `basePath` — Path to skill-tree storage directory (default: `.swarm/skill-tree/`)
 - `defaultProfile` — Default profile when no role-specific criteria exist (default: `""`)
 
+### Logging
+```json
+{
+  "template": "gsd",
+  "log": {
+    "level": "debug",
+    "dir": "/tmp/swarm-logs"
+  }
+}
+```
+
+Structured logging with leveled output (JSON Lines to file, human-readable to stderr). All log output goes through `src/log.mjs` via `createLogger("module")`.
+
+**Log levels** (each level includes all levels above it):
+- `error` — something broke
+- `warn` — degraded but functional (default)
+- `info` — lifecycle events (sidecar started, template loaded, package installed)
+- `debug` — verbose internals (cache hits, socket connects, IPC payloads)
+
+**Per-session log files**: Each Claude Code session writes to its own log file at `<dir>/<sessionId>.log`. The session ID comes from Claude Code's hook data and is available in all entry points (bootstrap, hooks, sidecar).
+
+**Default log directory**: `~/.claude-swarm/tmp/logs/` (always global, not project-scoped).
+
+Log options:
+- `level` — Log level threshold (default: `warn`)
+- `file` — Explicit log file path, overrides per-session paths (default: `""`)
+- `dir` — Directory for per-session log files (default: `~/.claude-swarm/tmp/logs/`)
+- `stderr` — Also write human-readable output to stderr (default: `true`)
+
+Quick debugging:
+```bash
+SWARM_LOG_LEVEL=debug claude    # all levels, per-session file
+SWARM_LOG_LEVEL=info claude     # lifecycle + warnings + errors
+```
+
 ### Available templates
 
 Templates are provided by the openteams package (installed via swarmkit). Built-in templates include:
@@ -252,6 +289,7 @@ All config values can be overridden via `SWARM_*` environment variables. Priorit
 | `map.scope` | `SWARM_MAP_SCOPE` | string | `""` (derived from template) |
 | `map.systemId` | `SWARM_MAP_SYSTEM_ID` | string | `system-claude-swarm` |
 | `map.sidecar` | `SWARM_MAP_SIDECAR` | string | `session` |
+| `map.reconnectIntervalMs` | `SWARM_MAP_RECONNECT_INTERVAL` | number (ms) | `60000` |
 | `map.auth.token` | `SWARM_MAP_AUTH_TOKEN` | string | `""` |
 | `map.auth.param` | `SWARM_MAP_AUTH_PARAM` | string | `token` |
 | `opentasks.enabled` | `SWARM_OPENTASKS_ENABLED` | boolean (`true`/`1`/`yes`) | `false` |
@@ -268,6 +306,10 @@ All config values can be overridden via `SWARM_*` environment variables. Priorit
 | `mesh.enabled` | `SWARM_MESH_ENABLED` | boolean (`true`/`1`/`yes`) | `false` |
 | `mesh.peerId` | `SWARM_MESH_PEER_ID` | string | `""` |
 | `mesh.mapServer` | `SWARM_MESH_MAP_SERVER` | string | `""` |
+| `log.level` | `SWARM_LOG_LEVEL` | string | `warn` |
+| `log.file` | `SWARM_LOG_FILE` | string | `""` (per-session default) |
+| `log.dir` | `SWARM_LOG_DIR` | string | `""` (`~/.claude-swarm/tmp/logs/`) |
+| `log.stderr` | `SWARM_LOG_STDERR` | boolean | `true` |
 
 MAP is implicitly enabled when `map.server` is configured (in file or via `SWARM_MAP_SERVER`). Use `SWARM_MAP_ENABLED=false` to explicitly disable.
 
@@ -381,7 +423,8 @@ All logic lives in `src/` as importable ES modules. Scripts in `scripts/` are th
 
 ```
 src/config.mjs            ← readConfig(), resolveScope(), resolveTeamName()
-src/paths.mjs              ← SWARM_DIR, CONFIG_PATH, TMP_DIR, TEAMS_DIR, MAP_DIR, teamDir()
+src/log.mjs                ← createLogger(), init() — structured leveled logging
+src/paths.mjs              ← SWARM_DIR, CONFIG_PATH, TMP_DIR, TEAMS_DIR, MAP_DIR, LOG_PATH, LOGS_DIR, teamDir()
 src/roles.mjs              ← readRoles(), matchRole(), writeRoles()
 src/inbox.mjs              ← readInbox(), clearInbox(), formatInboxAsMarkdown()
 src/map-connection.mjs     ← connectToMAP(), fireAndForget(), fireAndForgetTrajectory()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "Claude Code plugin for launching agent teams from openteams topologies with MAP observability",
   "type": "module",
   "exports": {
@@ -48,6 +48,9 @@
     "test:e2e:tier4": "vitest run --config e2e/vitest.config.e2e.mjs -t tier4",
     "test:e2e:tier5": "vitest run --config e2e/vitest.config.e2e.mjs -t tier5",
     "test:e2e:tier7": "vitest run --config e2e/vitest.config.e2e.mjs -t tier7",
+    "dev:link": "node scripts/dev-link.mjs link",
+    "dev:unlink": "node scripts/dev-link.mjs unlink",
+    "dev:status": "node scripts/dev-link.mjs status",
     "version:patch": "npm version patch --no-git-tag-version && node scripts/sync-version.mjs",
     "version:minor": "npm version minor --no-git-tag-version && node scripts/sync-version.mjs",
     "version:major": "npm version major --no-git-tag-version && node scripts/sync-version.mjs"

package/scripts/bootstrap-bg.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * bootstrap-bg.mjs — Background bootstrap worker
+ *
+ * Spawned as a detached child by bootstrap.mjs after the fast path completes.
+ * Handles slow operations: package version checks, sidecar startup, project init.
+ * Errors go to stderr (logged but don't affect the session).
+ */
+
+import { readConfig, resolveScope } from "../src/config.mjs";
+import { pluginDir } from "../src/paths.mjs";
+import { configureNodePath } from "../src/swarmkit-resolver.mjs";
+import { backgroundInit } from "../src/bootstrap.mjs";
+import { createLogger, init as initLog } from "../src/log.mjs";
+
+const log = createLogger("bootstrap:bg");
+
+try {
+  const args = JSON.parse(process.argv[2] || "{}");
+  const sessionId = args.sessionId || null;
+  const dir = pluginDir();
+
+  const config = readConfig();
+  initLog({ ...config.log, sessionId });
+  configureNodePath(dir);
+  const scope = resolveScope(config);
+
+  await backgroundInit(config, scope, dir, sessionId);
+} catch (err) {
+  log.error("background init failed", { error: err.message });
+}

package/scripts/bootstrap.mjs

@@ -2,14 +2,26 @@
 /**
  * bootstrap.mjs — SessionStart hook entry point
  *
- * Thin wrapper: delegates to src/bootstrap.mjs + src/context-output.mjs.
- * Reads session_id from stdin (provided by Claude Code hook system).
+ * Two-phase design for fast startup:
+ * 1. Fast path: reads config + cached team → writes context to stdout immediately
+ * 2. Background: spawns a detached child process for slow operations
+ *    (package checks, sidecar startup, project init)
+ *
  * Output goes to stdout → injected into Claude's context.
  * Exit 0 always — never block the session.
  */
 
 import { bootstrap } from "../src/bootstrap.mjs";
 import { formatBootstrapContext } from "../src/context-output.mjs";
+import { createLogger } from "../src/log.mjs";
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+import path from "path";
+
+const log = createLogger("bootstrap");
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 
 // ── Stdin reader ──────────────────────────────────────────────────────────────
 
@@ -23,7 +35,7 @@ function readStdin() {
       catch { resolve({}); }
     });
     if (process.stdin.readableEnded) resolve({});
-    setTimeout(() => resolve({}), 1000);
+    setTimeout(() => resolve({}), 200);
   });
 }
 
@@ -33,6 +45,7 @@ try {
   const hookData = await readStdin();
   const sessionId = hookData.session_id || null;
 
+  // Fast path: returns immediately with cached team + config
   const result = await bootstrap(undefined, sessionId);
   const output = formatBootstrapContext({
     template: result.template,
@@ -51,8 +64,21 @@ try {
     skilltreeStatus: result.skilltreeStatus,
   });
   process.stdout.write(output);
+
+  // Background path: spawn detached child for slow operations
+  // (package version checks, sidecar startup, project init)
+  const child = spawn(
+    process.execPath,
+    [path.join(__dirname, "bootstrap-bg.mjs"), JSON.stringify({ sessionId })],
+    {
+      detached: true,
+      stdio: "ignore",
+      env: { ...process.env, NODE_PATH: process.env.NODE_PATH || "" },
+    }
+  );
+  child.unref();
 } catch (err) {
-  process.stderr.write(`[bootstrap] Error: ${err.message}\n`);
+  log.error("bootstrap failed", { error: err.message });
   // Still output something useful
   process.stdout.write("## Claude Code Swarm\n\nUse `/swarm` to launch a team.\n");
 }

package/scripts/dev-link.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * dev-link.mjs — Link/unlink local plugin for development
+ *
+ * Replaces the installed plugin cache directory with a symlink to the local
+ * repo. Claude Code resolves CLAUDE_PLUGIN_ROOT from the original cache path,
+ * so we must symlink there (editing installed_plugins.json alone doesn't work).
+ *
+ * Usage:
+ *   npm run dev:link      — replace cache dir with symlink to local repo
+ *   npm run dev:unlink    — remove symlink, reinstall from marketplace
+ *   npm run dev:status    — check current link state
+ */
+
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { execSync } from "child_process";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const PLUGIN_ROOT = path.resolve(path.dirname(__filename), "..");
+const PLUGIN_KEY = "claude-code-swarm@claude-code-swarm";
+const MARKETPLACE_KEY = "claude-code-swarm";
+const PLUGINS_DIR = path.join(os.homedir(), ".claude", "plugins");
+const CACHE_DIR = path.join(PLUGINS_DIR, "cache");
+const INSTALLED_PLUGINS_PATH = path.join(PLUGINS_DIR, "installed_plugins.json");
+const MARKETPLACES_PATH = path.join(PLUGINS_DIR, "known_marketplaces.json");
+
+const action = process.argv[2];
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch {
+    console.error(`Could not read ${filePath}`);
+    process.exit(1);
+  }
+}
+
+function getPluginEntry() {
+  const data = readJson(INSTALLED_PLUGINS_PATH);
+  const entries = data.plugins?.[PLUGIN_KEY];
+  if (!entries?.length) {
+    console.error(`Plugin "${PLUGIN_KEY}" not found in installed_plugins.json`);
+    process.exit(1);
+  }
+  return { data, entry: entries[0] };
+}
+
+function getMarketplacePath() {
+  const data = readJson(MARKETPLACES_PATH);
+  const marketplace = data[MARKETPLACE_KEY];
+  if (!marketplace?.installLocation) {
+    console.error(`Marketplace "${MARKETPLACE_KEY}" not found in known_marketplaces.json`);
+    process.exit(1);
+  }
+  return marketplace.installLocation;
+}
+
+function isSymlink(p) {
+  try {
+    return fs.lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the cache path that Claude Code actually uses for CLAUDE_PLUGIN_ROOT.
+ * This is the installPath from installed_plugins.json (usually under ~/.claude/plugins/cache/).
+ */
+function getCachePath() {
+  const { entry } = getPluginEntry();
+  // If installPath was already changed to local repo, look for the original
+  if (entry.installPath === PLUGIN_ROOT && entry._originalInstallPath) {
+    return entry._originalInstallPath;
+  }
+  return entry.installPath;
+}
+
+function link() {
+  const cachePath = getCachePath();
+
+  if (isSymlink(cachePath)) {
+    const target = fs.readlinkSync(cachePath);
+    if (target === PLUGIN_ROOT) {
+      console.log(`Already linked: ${cachePath} → ${PLUGIN_ROOT}`);
+      return;
+    }
+    console.error(`Already symlinked to a different target: ${target}`);
+    process.exit(1);
+  }
+
+  // Remove the cached copy
+  if (fs.existsSync(cachePath)) {
+    fs.rmSync(cachePath, { recursive: true, force: true });
+    console.log(`Removed cached copy: ${cachePath}`);
+  }
+
+  // Ensure parent directory exists
+  fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+
+  // Create symlink
+  fs.symlinkSync(PLUGIN_ROOT, cachePath, "dir");
+  console.log(`Linked: ${cachePath} → ${PLUGIN_ROOT}`);
+  console.log("\nRestart Claude Code for changes to take effect.");
+}
+
+function unlink() {
+  const cachePath = getCachePath();
+
+  if (!isSymlink(cachePath)) {
+    console.log(`Not linked (${cachePath} is not a symlink)`);
+    return;
+  }
+
+  // Remove symlink
+  fs.unlinkSync(cachePath);
+  console.log(`Removed symlink: ${cachePath}`);
+
+  // Reinstall from marketplace clone
+  const marketplacePath = getMarketplacePath();
+  const pluginDir = path.join(marketplacePath, ".claude-plugin");
+
+  if (!fs.existsSync(pluginDir)) {
+    console.error(`Marketplace clone missing .claude-plugin/ at ${marketplacePath}`);
+    console.error("Run 'claude plugins update' to reinstall.");
+    process.exit(1);
+  }
+
+  // Copy marketplace clone to cache
+  fs.cpSync(marketplacePath, cachePath, { recursive: true });
+
+  // Install production deps
+  try {
+    execSync("npm install --production --ignore-scripts", {
+      cwd: cachePath,
+      stdio: ["ignore", "ignore", "pipe"],
+    });
+  } catch {
+    console.warn("Warning: npm install failed, plugin may not work correctly");
+  }
+
+  const pkgJson = readJson(path.join(cachePath, "package.json"));
+  console.log(`Unlinked: reinstalled from marketplace at ${cachePath} (v${pkgJson.version})`);
+  console.log("\nRestart Claude Code for changes to take effect.");
+}
+
+function status() {
+  const cachePath = getCachePath();
+
+  if (isSymlink(cachePath)) {
+    const target = fs.readlinkSync(cachePath);
+    console.log(`LINKED: ${cachePath} → ${target}`);
+  } else if (fs.existsSync(cachePath)) {
+    const pkgPath = path.join(cachePath, "package.json");
+    const version = fs.existsSync(pkgPath) ? readJson(pkgPath).version : "?";
+    console.log(`NOT LINKED: using cached copy at ${cachePath} (v${version})`);
+  } else {
+    console.log(`MISSING: ${cachePath} does not exist`);
+    console.log(`  Run 'npm run dev:link' to create symlink.`);
+  }
+}
+
+switch (action) {
+  case "link":
+    link();
+    break;
+  case "unlink":
+    unlink();
+    break;
+  case "status":
+    status();
+    break;
+  default:
+    console.error("Usage: dev-link.mjs <link|unlink|status>");
+    process.exit(1);
+}

package/scripts/map-hook.mjs

@@ -25,6 +25,9 @@
  */
 
 import { readConfig, resolveTeamName } from "../src/config.mjs";
+import { createLogger, init as initLog } from "../src/log.mjs";
+
+const log = createLogger("map-hook");
 import { readRoles, matchRole } from "../src/roles.mjs";
 import { formatInboxAsMarkdown } from "../src/inbox.mjs";
 import { sendToInbox } from "../src/sidecar-client.mjs";
@@ -63,10 +66,7 @@ function readStdin() {
 
 // ── Action handlers ───────────────────────────────────────────────────────────
 
-async function handleInject() {
-  // Read stdin to get session_id for per-session inbox routing
-  const hookData = await readStdin();
-  const sessionId = hookData.session_id || null;
+async function handleInject(hookData, sessionId) {
   const sPaths = sessionPaths(sessionId);
   const config = readConfig();
 
@@ -99,48 +99,37 @@ async function handleInject() {
   if (output) process.stdout.write(output);
 }
 
-async function handleTurnCompleted() {
+async function handleTurnCompleted(hookData, sessionId) {
   const config = readConfig();
-  const hookData = await readStdin();
-  const sessionId = hookData.session_id || null;
 
   // Update sidecar state to idle (server auto-emits agent_state_changed)
   const stopReason = hookData.stop_reason || "end_turn";
   await sendCommand(config, buildStateCommand(null, "idle", { lastStopReason: stopReason }), sessionId);
 }
 
-async function handleSessionlogSync() {
+async function handleSessionlogSync(hookData, sessionId) {
   const config = readConfig();
-  const hookData = await readStdin();
-  const sessionId = hookData.session_id || null;
-
   await syncSessionlog(config, sessionId);
 }
 
-async function handleSubagentStart() {
+async function handleSubagentStart(hookData, sessionId) {
   const config = readConfig();
-  const hookData = await readStdin();
-  const sessionId = hookData.session_id || null;
   const teamName = resolveTeamName(config);
 
   // Spawn subagent in MAP (server auto-emits agent_registered)
   await sendCommand(config, buildSubagentSpawnCommand(hookData, teamName), sessionId);
 }
 
-async function handleSubagentStop() {
+async function handleSubagentStop(hookData, sessionId) {
   const config = readConfig();
-  const hookData = await readStdin();
-  const sessionId = hookData.session_id || null;
   const teamName = resolveTeamName(config);
 
   // Mark subagent done (server auto-emits agent_unregistered)
   await sendCommand(config, buildSubagentDoneCommand(hookData, teamName), sessionId);
 }
 
-async function handleTeammateIdle() {
+async function handleTeammateIdle(hookData, sessionId) {
   const config = readConfig();
-  const hookData = await readStdin();
-  const sessionId = hookData.session_id || null;
   const roles = readRoles();
   const teamName = resolveTeamName(config);
 
@@ -154,10 +143,8 @@ async function handleTeammateIdle() {
   await sendCommand(config, buildStateCommand(agentId, "idle", { teammateName }), sessionId);
 }
 
-async function handleTaskCompletedHook() {
+async function handleTaskCompletedHook(hookData, sessionId) {
   const config = readConfig();
-  const hookData = await readStdin();
-  const sessionId = hookData.session_id || null;
   const roles = readRoles();
   const teamName = resolveTeamName(config);
 
@@ -168,56 +155,55 @@ async function handleTaskCompletedHook() {
   await handleTaskStatusCompleted(config, hookData, teamName, matchedRole, sessionId);
 }
 
-async function handleOpentasksMcpUsed() {
+async function handleOpentasksMcpUsed(hookData, sessionId) {
   const config = readConfig();
   if (!config.map.enabled) return; // Only bridge when MAP is enabled
 
-  const hookData = await readStdin();
-  const sessionId = hookData.session_id || null;
   const commands = buildOpentasksBridgeCommands(hookData);
   for (const cmd of commands) {
     await sendCommand(config, cmd, sessionId);
   }
 }
 
-async function handleNativeTaskCreated() {
+async function handleNativeTaskCreated(hookData, sessionId) {
   const config = readConfig();
   if (!config.map?.enabled) return;
 
-  const hookData = await readStdin();
-  const sessionId = hookData.session_id || null;
   await handleNativeTaskCreatedEvent(config, hookData, sessionId);
 }
 
-async function handleNativeTaskUpdated() {
+async function handleNativeTaskUpdated(hookData, sessionId) {
   const config = readConfig();
   if (!config.map?.enabled) return;
 
-  const hookData = await readStdin();
-  const sessionId = hookData.session_id || null;
   await handleNativeTaskUpdatedEvent(config, hookData, sessionId);
 }
 
 // ── Main ──────────────────────────────────────────────────────────────────────
 
 async function main() {
+  const hookData = await readStdin();
+  const sessionId = hookData.session_id || null;
+  const config = readConfig();
+  initLog({ ...config.log, sessionId });
+
   try {
     switch (action) {
-      case "inject": await handleInject(); break;
-      case "turn-completed": await handleTurnCompleted(); break;
-      case "sessionlog-sync": await handleSessionlogSync(); break;
-      case "subagent-start": await handleSubagentStart(); break;
-      case "subagent-stop": await handleSubagentStop(); break;
-      case "teammate-idle": await handleTeammateIdle(); break;
-      case "task-completed": await handleTaskCompletedHook(); break;
-      case "opentasks-mcp-used": await handleOpentasksMcpUsed(); break;
-      case "native-task-created": await handleNativeTaskCreated(); break;
-      case "native-task-updated": await handleNativeTaskUpdated(); break;
+      case "inject": await handleInject(hookData, sessionId); break;
+      case "turn-completed": await handleTurnCompleted(hookData, sessionId); break;
+      case "sessionlog-sync": await handleSessionlogSync(hookData, sessionId); break;
+      case "subagent-start": await handleSubagentStart(hookData, sessionId); break;
+      case "subagent-stop": await handleSubagentStop(hookData, sessionId); break;
+      case "teammate-idle": await handleTeammateIdle(hookData, sessionId); break;
+      case "task-completed": await handleTaskCompletedHook(hookData, sessionId); break;
+      case "opentasks-mcp-used": await handleOpentasksMcpUsed(hookData, sessionId); break;
+      case "native-task-created": await handleNativeTaskCreated(hookData, sessionId); break;
+      case "native-task-updated": await handleNativeTaskUpdated(hookData, sessionId); break;
       default:
-        process.stderr.write(`[map-hook] Unknown action: ${action}\n`);
+        log.warn("unknown action", { action });
     }
   } catch (err) {
-    process.stderr.write(`[map-hook] Error in ${action}: ${err.message}\n`);
+    log.error("hook action failed", { action, error: err.message });
   }
 }