claude-code-swarm 0.3.3 → 0.3.4

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "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.3",
+  "version": "0.3.4",
   "author": {
     "name": "alexngai"
   }

package/CLAUDE.md

@@ -105,6 +105,8 @@ 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)
+- `auth.token` — Authentication token appended as a query parameter to the server URL
+- `auth.param` — Query parameter name for the token (default: `token`)
 
 ### With sessionlog → MAP sync
 ```json
@@ -154,6 +156,8 @@ 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.auth.token` | `SWARM_MAP_AUTH_TOKEN` | string | `""` |
+| `map.auth.param` | `SWARM_MAP_AUTH_PARAM` | string | `token` |
 | `sessionlog.enabled` | `SWARM_SESSIONLOG_ENABLED` | boolean (`true`/`1`/`yes`) | `false` |
 | `sessionlog.sync` | `SWARM_SESSIONLOG_SYNC` | string | `off` |
 

package/README.md

@@ -58,6 +58,71 @@ npm install -g openteams
 openteams editor
 ```
 
+## Configuration
+
+### Config resolution
+
+Configuration is resolved with tiered fallthrough — each level overrides the one below:
+
+```
+SWARM_* env vars  >  project config  >  global config  >  defaults
+```
+
+### Project config
+
+Lives in your project directory at `.swarm/claude-swarm/config.json` (or `.claude-swarm/config.json` with `--no-prefix`):
+
+```json
+{
+  "template": "get-shit-done",
+  "map": {
+    "scope": "my-project",
+    "systemId": "my-project-swarm"
+  }
+}
+```
+
+Project config is typically committed to the repo or gitignored per preference.
+
+### Global config
+
+Lives at `~/.claude-swarm/config.json`. Created by `swarmkit init` or manually. Sets user-wide defaults that apply to all projects unless overridden:
+
+```json
+{
+  "map": {
+    "server": "ws://my-map-server:8080",
+    "sidecar": "session",
+    "auth": {
+      "token": "my-token"
+    }
+  },
+  "sessionlog": {
+    "enabled": true,
+    "sync": "metrics"
+  }
+}
+```
+
+This is useful for settings you don't want to repeat in every project — MAP server address, auth tokens, sidecar mode, sessionlog preferences. Fields like `template` and `map.scope` are typically project-specific and belong in the project config.
+
+### Environment variable overrides
+
+All config values can be overridden via `SWARM_*` environment variables:
+
+| Config field | Environment variable |
+|---|---|
+| `template` | `SWARM_TEMPLATE` |
+| `map.server` | `SWARM_MAP_SERVER` |
+| `map.enabled` | `SWARM_MAP_ENABLED` |
+| `map.scope` | `SWARM_MAP_SCOPE` |
+| `map.systemId` | `SWARM_MAP_SYSTEM_ID` |
+| `map.sidecar` | `SWARM_MAP_SIDECAR` |
+| `map.auth.token` | `SWARM_MAP_AUTH_TOKEN` |
+| `map.auth.param` | `SWARM_MAP_AUTH_PARAM` |
+| `sessionlog.enabled` | `SWARM_SESSIONLOG_ENABLED` |
+| `sessionlog.sync` | `SWARM_SESSIONLOG_SYNC` |
+
 ## How it works
 
 1. **SessionStart hook** ensures `openteams` is installed and reads your team configuration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Claude Code plugin for launching agent teams from openteams topologies with MAP observability",
   "type": "module",
   "exports": {

package/src/__tests__/config.test.mjs

@@ -102,6 +102,112 @@ describe("config", () => {
     });
   });
 
+  describe("global config fallthrough", () => {
+    let tmpDir;
+    beforeEach(() => { tmpDir = makeTmpDir(); });
+    afterEach(() => { cleanupTmpDir(tmpDir); });
+
+    it("uses global config values when project config is missing", () => {
+      const globalPath = writeFile(tmpDir, "global.json", JSON.stringify({
+        map: { server: "ws://global-server:9090", sidecar: "persistent" },
+        sessionlog: { sync: "full" },
+      }));
+      const projectPath = path.join(tmpDir, "nonexistent.json");
+      const config = readConfig(projectPath, globalPath);
+      expect(config.map.server).toBe("ws://global-server:9090");
+      expect(config.map.sidecar).toBe("persistent");
+      expect(config.sessionlog.sync).toBe("full");
+    });
+
+    it("project config overrides global config", () => {
+      const globalPath = writeFile(tmpDir, "global.json", JSON.stringify({
+        map: { server: "ws://global-server:9090", sidecar: "persistent" },
+        sessionlog: { sync: "full" },
+      }));
+      const projectPath = writeFile(tmpDir, "project.json", JSON.stringify({
+        map: { server: "ws://project-server:8080" },
+        sessionlog: { sync: "lifecycle" },
+      }));
+      const config = readConfig(projectPath, globalPath);
+      expect(config.map.server).toBe("ws://project-server:8080");
+      expect(config.map.sidecar).toBe("persistent"); // falls through from global
+      expect(config.sessionlog.sync).toBe("lifecycle");
+    });
+
+    it("project template overrides global template", () => {
+      const globalPath = writeFile(tmpDir, "global.json", JSON.stringify({
+        template: "global-template",
+      }));
+      const projectPath = writeFile(tmpDir, "project.json", JSON.stringify({
+        template: "project-template",
+      }));
+      const config = readConfig(projectPath, globalPath);
+      expect(config.template).toBe("project-template");
+    });
+
+    it("global template is used when project has no template", () => {
+      const globalPath = writeFile(tmpDir, "global.json", JSON.stringify({
+        template: "global-template",
+      }));
+      const projectPath = writeFile(tmpDir, "project.json", JSON.stringify({}));
+      const config = readConfig(projectPath, globalPath);
+      expect(config.template).toBe("global-template");
+    });
+
+    it("global map.enabled enables MAP when project has no map config", () => {
+      const globalPath = writeFile(tmpDir, "global.json", JSON.stringify({
+        map: { enabled: true, server: "ws://global-server:9090" },
+      }));
+      const projectPath = path.join(tmpDir, "nonexistent.json");
+      const config = readConfig(projectPath, globalPath);
+      expect(config.map.enabled).toBe(true);
+      expect(config.map.server).toBe("ws://global-server:9090");
+    });
+
+    it("global map.server implicitly enables MAP when project has no config", () => {
+      const globalPath = writeFile(tmpDir, "global.json", JSON.stringify({
+        map: { server: "ws://global-server:9090" },
+      }));
+      const projectPath = path.join(tmpDir, "nonexistent.json");
+      const config = readConfig(projectPath, globalPath);
+      expect(config.map.enabled).toBe(true);
+    });
+
+    it("global sessionlog.enabled is used when project has no sessionlog config", () => {
+      const globalPath = writeFile(tmpDir, "global.json", JSON.stringify({
+        sessionlog: { enabled: true, sync: "metrics" },
+      }));
+      const projectPath = path.join(tmpDir, "nonexistent.json");
+      const config = readConfig(projectPath, globalPath);
+      expect(config.sessionlog.enabled).toBe(true);
+      expect(config.sessionlog.sync).toBe("metrics");
+    });
+
+    it("falls back to defaults when both configs are missing", () => {
+      const globalPath = path.join(tmpDir, "nonexistent-global.json");
+      const projectPath = path.join(tmpDir, "nonexistent-project.json");
+      const config = readConfig(projectPath, globalPath);
+      expect(config.template).toBe("");
+      expect(config.map.enabled).toBe(false);
+      expect(config.map.server).toBe(DEFAULTS.mapServer);
+      expect(config.sessionlog.enabled).toBe(false);
+      expect(config.sessionlog.sync).toBe(DEFAULTS.sessionlogSync);
+    });
+
+    it("per-field fallthrough: project scope + global server", () => {
+      const globalPath = writeFile(tmpDir, "global.json", JSON.stringify({
+        map: { server: "ws://global-server:9090", systemId: "global-system" },
+      }));
+      const projectPath = writeFile(tmpDir, "project.json", JSON.stringify({
+        map: { scope: "my-project" },
+      }));
+      const config = readConfig(projectPath, globalPath);
+      expect(config.map.scope).toBe("my-project");
+      expect(config.map.server).toBe("ws://global-server:9090");
+      expect(config.map.systemId).toBe("global-system");
+    });
+  });
+
   describe("resolveScope", () => {
     it("returns explicit scope when config.map.scope is set", () => {
       expect(resolveScope({ map: { scope: "custom:scope" }, template: "test" })).toBe("custom:scope");
@@ -268,6 +374,28 @@ describe("config", () => {
       expect(config.template).toBe("file-template");
       expect(config.map.server).toBe("ws://file-server:8080");
     });
+
+    it("env vars override global config values", () => {
+      process.env.SWARM_MAP_SERVER = "ws://env-server:9090";
+      const globalPath = writeFile(tmpDir, "global.json", JSON.stringify({
+        map: { server: "ws://global-server:8080" },
+      }));
+      const projectPath = path.join(tmpDir, "nonexistent.json");
+      const config = readConfig(projectPath, globalPath);
+      expect(config.map.server).toBe("ws://env-server:9090");
+    });
+
+    it("env vars override both project and global config", () => {
+      process.env.SWARM_MAP_SIDECAR = "persistent";
+      const globalPath = writeFile(tmpDir, "global.json", JSON.stringify({
+        map: { sidecar: "session" },
+      }));
+      const projectPath = writeFile(tmpDir, "project.json", JSON.stringify({
+        map: { sidecar: "session" },
+      }));
+      const config = readConfig(projectPath, globalPath);
+      expect(config.map.sidecar).toBe("persistent");
+    });
   });
 
   describe("resolveTeamName", () => {

package/src/__tests__/index.test.mjs

@@ -14,6 +14,8 @@ describe("index", () => {
   it("exports PID_PATH", () => expect(typeof index.PID_PATH).toBe("string"));
   it("exports ROLES_PATH", () => expect(typeof index.ROLES_PATH).toBe("string"));
   it("exports CONFIG_PATH", () => expect(typeof index.CONFIG_PATH).toBe("string"));
+  it("exports GLOBAL_CONFIG_DIR", () => expect(typeof index.GLOBAL_CONFIG_DIR).toBe("string"));
+  it("exports GLOBAL_CONFIG_PATH", () => expect(typeof index.GLOBAL_CONFIG_PATH).toBe("string"));
   it("exports TMP_DIR", () => expect(typeof index.TMP_DIR).toBe("string"));
   it("exports TEAMS_DIR", () => expect(typeof index.TEAMS_DIR).toBe("string"));
   it("exports teamDir", () => expect(typeof index.teamDir).toBe("function"));

package/src/__tests__/paths.test.mjs

@@ -1,8 +1,11 @@
 import { describe, it, expect } from "vitest";
 import path from "path";
+import os from "os";
+import path from "path";
 import {
   SWARM_DIR, SOCKET_PATH, INBOX_PATH, PID_PATH, ROLES_PATH,
   CONFIG_PATH, TMP_DIR, TEAMS_DIR, MAP_DIR,
+  GLOBAL_CONFIG_DIR, GLOBAL_CONFIG_PATH,
   teamDir, pluginDir,
 } from "../paths.mjs";
 
@@ -60,6 +63,16 @@ describe("paths", () => {
     });
   });
 
+  describe("global config paths", () => {
+    it("GLOBAL_CONFIG_DIR is under ~/.swarmkit/", () => {
+      expect(GLOBAL_CONFIG_DIR).toBe(path.join(os.homedir(), ".claude-swarm"));
+    });
+
+    it("GLOBAL_CONFIG_PATH is config.json under GLOBAL_CONFIG_DIR", () => {
+      expect(GLOBAL_CONFIG_PATH).toBe(path.join(os.homedir(), ".claude-swarm", "config.json"));
+    });
+  });
+
   describe("pluginDir", () => {
     it("resolves to the repository root (parent of src/)", () => {
       const dir = pluginDir();

package/src/config.mjs

@@ -6,7 +6,7 @@
  */
 
 import fs from "fs";
-import { CONFIG_PATH } from "./paths.mjs";
+import { CONFIG_PATH, GLOBAL_CONFIG_PATH } from "./paths.mjs";
 
 export const DEFAULTS = {
   mapServer: "ws://localhost:8080",
@@ -34,40 +34,70 @@ function envStr(name) {
 }
 
 /**
- * Read and normalize .swarm/claude/config.json config.
- * Priority: SWARM_* env vars > config file > defaults.
- * Never throws — returns defaults on any error.
+ * Read a JSON config file. Returns empty object on any error.
  */
-export function readConfig(configPath = CONFIG_PATH) {
-  let raw = {};
+function readJsonFile(filePath) {
   try {
-    raw = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
   } catch {
-    // Missing or invalid config file — raw stays empty, defaults apply
+    return {};
   }
+}
+
+/**
+ * Read and normalize config with tiered resolution.
+ * Priority: SWARM_* env vars > project config file > global config file > defaults.
+ * Never throws — returns defaults on any error.
+ */
+export function readConfig(configPath = CONFIG_PATH, globalConfigPath = GLOBAL_CONFIG_PATH) {
+  const global = readJsonFile(globalConfigPath);
+  const project = readJsonFile(configPath);
 
-  const server = envStr("SWARM_MAP_SERVER") ?? raw.map?.server ?? undefined;
-  const explicitEnabled = envBool("SWARM_MAP_ENABLED") ?? (raw.map?.enabled === true ? true : undefined);
+  // Project overrides global for each field (not deep merge — per-field fallthrough)
+  const server = envStr("SWARM_MAP_SERVER") ?? project.map?.server ?? global.map?.server ?? undefined;
+  const explicitEnabled = envBool("SWARM_MAP_ENABLED") ?? (project.map?.enabled === true ? true : undefined) ?? (global.map?.enabled === true ? true : undefined);
 
   // MAP is enabled if explicitly set OR if a server is configured
   const mapEnabled = explicitEnabled ?? (server !== undefined);
 
   return {
-    template: envStr("SWARM_TEMPLATE") ?? raw.template ?? "",
+    template: envStr("SWARM_TEMPLATE") ?? project.template ?? global.template ?? "",
     map: {
       enabled: mapEnabled,
       server: server || DEFAULTS.mapServer,
-      scope: envStr("SWARM_MAP_SCOPE") ?? raw.map?.scope ?? "",
-      systemId: envStr("SWARM_MAP_SYSTEM_ID") ?? raw.map?.systemId ?? DEFAULTS.mapSystemId,
-      sidecar: envStr("SWARM_MAP_SIDECAR") ?? raw.map?.sidecar ?? DEFAULTS.mapSidecar,
+      scope: envStr("SWARM_MAP_SCOPE") ?? project.map?.scope ?? global.map?.scope ?? "",
+      systemId: envStr("SWARM_MAP_SYSTEM_ID") ?? project.map?.systemId ?? global.map?.systemId ?? DEFAULTS.mapSystemId,
+      sidecar: envStr("SWARM_MAP_SIDECAR") ?? project.map?.sidecar ?? global.map?.sidecar ?? DEFAULTS.mapSidecar,
+      auth: {
+        token: envStr("SWARM_MAP_AUTH_TOKEN") ?? project.map?.auth?.token ?? global.map?.auth?.token ?? "",
+        param: envStr("SWARM_MAP_AUTH_PARAM") ?? project.map?.auth?.param ?? global.map?.auth?.param ?? "token",
+      },
     },
     sessionlog: {
-      enabled: envBool("SWARM_SESSIONLOG_ENABLED") ?? Boolean(raw.sessionlog?.enabled),
-      sync: envStr("SWARM_SESSIONLOG_SYNC") ?? raw.sessionlog?.sync ?? DEFAULTS.sessionlogSync,
+      enabled: envBool("SWARM_SESSIONLOG_ENABLED") ?? Boolean(project.sessionlog?.enabled ?? global.sessionlog?.enabled),
+      sync: envStr("SWARM_SESSIONLOG_SYNC") ?? project.sessionlog?.sync ?? global.sessionlog?.sync ?? DEFAULTS.sessionlogSync,
     },
   };
 }
 
+/**
+ * Build the MAP server URL with auth query param if configured.
+ * If the token is already in the server URL, returns as-is.
+ */
+export function resolveMapServer(config) {
+  const server = config.map?.server || DEFAULTS.mapServer;
+  const token = config.map?.auth?.token;
+  if (!token) return server;
+
+  // Don't double-add if token is already in the URL
+  const url = new URL(server);
+  const param = config.map?.auth?.param || "token";
+  if (url.searchParams.has(param)) return server;
+
+  url.searchParams.set(param, token);
+  return url.toString();
+}
+
 /**
  * Derive MAP scope from config.
  * Priority: explicit scope > swarm:<template> > swarm:default

package/src/index.mjs

@@ -3,7 +3,7 @@
  */
 
 // Config
-export { readConfig, resolveScope, resolveTeamName, DEFAULTS } from "./config.mjs";
+export { readConfig, resolveScope, resolveTeamName, resolveMapServer, DEFAULTS } from "./config.mjs";
 
 // Paths
 export {
@@ -14,6 +14,8 @@ export {
   ROLES_PATH,
   SESSIONLOG_STATE_PATH,
   CONFIG_PATH,
+  GLOBAL_CONFIG_DIR,
+  GLOBAL_CONFIG_PATH,
   SESSIONLOG_DIR,
   TMP_DIR,
   TEAMS_DIR,

package/src/map-connection.mjs

@@ -5,7 +5,7 @@
  * for when the sidecar is unavailable.
  */
 
-import { resolveScope, resolveTeamName, DEFAULTS } from "./config.mjs";
+import { resolveScope, resolveTeamName, resolveMapServer, DEFAULTS } from "./config.mjs";
 
 /**
  * Connect to a MAP server as an agent.
@@ -60,7 +60,7 @@ export async function connectToMAP({ server, scope, systemId, onMessage }) {
 export async function fireAndForget(config, event) {
   try {
     const { AgentConnection } = await import("@multi-agent-protocol/sdk");
-    const server = config.map?.server || DEFAULTS.mapServer;
+    const server = resolveMapServer(config);
     const scope = resolveScope(config);
     const teamName = resolveTeamName(config);
 
@@ -84,7 +84,7 @@ export async function fireAndForget(config, event) {
 export async function fireAndForgetTrajectory(config, checkpoint) {
   try {
     const { AgentConnection } = await import("@multi-agent-protocol/sdk");
-    const server = config.map?.server || DEFAULTS.mapServer;
+    const server = resolveMapServer(config);
     const scope = resolveScope(config);
     const teamName = resolveTeamName(config);
 

package/src/paths.mjs

@@ -14,12 +14,17 @@
 
 import fs from "fs";
 import path from "path";
+import os from "os";
 import { fileURLToPath } from "url";
 
 // Root plugin directory within .swarm
 export const SWARM_DIR = ".swarm/claude-swarm";
 export const CONFIG_PATH = ".swarm/claude-swarm/config.json";
 
+// Global config directory (~/.claude-swarm/)
+export const GLOBAL_CONFIG_DIR = path.join(os.homedir(), ".claude-swarm");
+export const GLOBAL_CONFIG_PATH = path.join(GLOBAL_CONFIG_DIR, "config.json");
+
 // Temporary/generated artifacts (gitignored)
 export const TMP_DIR = ".swarm/claude-swarm/tmp";
 

package/src/sidecar-client.mjs

@@ -9,7 +9,7 @@ import path from "path";
 import net from "net";
 import { spawn } from "child_process";
 import { SOCKET_PATH, PID_PATH, pluginDir } from "./paths.mjs";
-import { resolveScope, DEFAULTS } from "./config.mjs";
+import { resolveScope, resolveMapServer, DEFAULTS } from "./config.mjs";
 
 /**
  * Send a command to the sidecar via UNIX socket.
@@ -52,7 +52,7 @@ export async function startSidecar(config, pluginDirOverride) {
   const dir = pluginDirOverride || pluginDir();
   const sidecarPath = path.join(dir, "scripts", "map-sidecar.mjs");
 
-  const server = config.map?.server || DEFAULTS.mapServer;
+  const server = resolveMapServer(config);
   const scope = resolveScope(config);
   const systemId = config.map?.systemId || DEFAULTS.mapSystemId;