@ra3orblade/swarm 0.4.1 → 0.5.0

package/README.md

@@ -22,7 +22,7 @@ A local-first control plane for AI-agent development on any repository.</p>
   <a href="LICENSE"><img alt="Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-lightgrey?labelColor=0e1013"></a>
 </p>
 
-<p align="center"><a href="https://getswarm.vercel.app"><img src="docs/art/screens/fleet.jpg" alt="Swarm Fleet view — every agent session on the machine, live" width="100%"></a></p>
+<p align="center"><a href="https://getswarm.vercel.app"><img src="docs/art/screens/fleet.png" alt="Swarm Fleet view — every agent session on the machine, live" width="100%"></a></p>
 
 Run more than one [Claude Code](https://claude.com/claude-code) session at a time — or a [Codex CLI](https://github.com/openai/codex) or Grok run on the side — and you lose the thread fast: which session is on which branch, what it's costing, which worktree has uncommitted work nobody owns, why that edit got blocked. Swarm is one daemon that watches every session on your machine — live tool calls, reasoning, token spend, cost — keeps a ledger of who holds which task, worktree and runtime resource, turns the "never do X" prose in `CLAUDE.md` into real permission decisions, and streams all of it to one dashboard.
 
@@ -42,11 +42,11 @@ bunx @ra3orblade/swarm setup
 
 **Session** — an agent's reasoning and tool calls as a live stream, with cost per turn, cache hit rate, thinking share, tool histogram and the transcript path.
 
-<p align="center"><img src="docs/art/screens/session.jpg" alt="Session view — live reasoning stream with a stats panel" width="100%"></p>
+<p align="center"><img src="docs/art/screens/session.png" alt="Session view — live reasoning stream with a stats panel" width="100%"></p>
 
 **Board** — the coordination ledger for a project: task **claims** (each in an isolated git worktree), **worktrees** with branch, dirty/unpushed state and which session is inside, **runtime resources** (ports, dev servers, databases held as named singletons), and **incidents** — every command the rules asked about or denied, with the rule and the command.
 
-<p align="center"><img src="docs/art/screens/board.jpg" alt="Board view — worktrees and incidents" width="100%"></p>
+<p align="center"><img src="docs/art/screens/board.png" alt="Board view — worktrees and incidents" width="100%"></p>
 
 **Rules** — guardrails on the Bash commands a Claude Code session runs: `shared_tree`, `destructive_git`, `pattern_kill`, `protected_ports`, plus `no_foreign_worktree` and the opt-in `claim_required_to_write` on file writes; each `ask | deny | off` per repo in `.swarm.toml`. A `deny` is returned to Claude Code as a real permission denial. Ports held as resources are protected automatically. Guardrails against accidents, not a sandbox — see [what rules are and aren't](https://getswarm.vercel.app/docs/03-rules-and-config#what-rules-are--and-arent).
 
@@ -54,11 +54,11 @@ bunx @ra3orblade/swarm setup
 
 **Timeline** — session lanes per project, coloured by agent, 3–72 h.
 
-<p align="center"><img src="docs/art/screens/timeline.jpg" alt="Timeline view — session lanes per project" width="100%"></p>
+<p align="center"><img src="docs/art/screens/timeline.png" alt="Timeline view — session lanes per project" width="100%"></p>
 
 **Spend & Stats** — cost by project, model and agent, today and all-time; plus the fun numbers: tokens, turns, streaks, activity calendar, words written, what it adds up to in novels and coffee.
 
-<p align="center"><img src="docs/art/screens/stats.jpg" alt="Stats view" width="100%"></p>
+<p align="center"><img src="docs/art/screens/stats.png" alt="Stats view" width="100%"></p>
 
 **Multi-agent** — Claude Code via its hooks and transcripts; Codex CLI and Grok by tailing the session logs they already write (`~/.codex`, ACP `updates.jsonl`). Every session is tagged with its agent; Spend breaks down per agent.
 

package/dist/swarm-mcp.js

@@ -19723,6 +19723,7 @@ async function ensureDaemon(opts = {}) {
 }
 // packages/mcp/src/server.ts
 var OWNER = process.env.SWARM_OWNER ?? "agent";
+var SESSION = process.env.CLAUDE_SESSION_ID ?? null;
 async function api2(path, init) {
   const base = await ensureDaemon({ quiet: true }).catch(() => resolveBaseUrl());
   const r = await fetch(`${base}${path}`, init);
@@ -19782,6 +19783,92 @@ function buildServer() {
     const n = ready[0];
     return ok(`next: ${n.id} \u2014 ${n.title} (claim it with swarm_claim)`, n);
   });
+  server.registerTool("swarm_handoff", {
+    title: "Leave a handoff",
+    description: "Before stopping or releasing a task, record what was done, what remains (in order), files worth reading first, and how to verify. The next session that starts in this task's worktree receives it automatically as context; `swarm_resume` reads it on demand.",
+    inputSchema: {
+      task: exports_external.string(),
+      done: exports_external.string().describe("what was finished"),
+      remaining: exports_external.string().describe("what is left, in the order to do it"),
+      files: exports_external.array(exports_external.string()).optional().describe("files touched or to read first"),
+      verify: exports_external.string().optional().describe("how to verify the work so far")
+    }
+  }, async ({ task, done, remaining, files, verify }) => {
+    const pid = await projectId();
+    const r = await api2("/v1/handoffs", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        projectId: pid,
+        task,
+        done,
+        remaining,
+        files: files ?? [],
+        verify: verify ?? null,
+        by: OWNER,
+        sessionId: SESSION
+      })
+    });
+    if (!r.ok)
+      return fail(`REFUSED: ${r.error}`);
+    return ok(`handoff recorded on ${task}`, r.handoff);
+  });
+  server.registerTool("swarm_resume", {
+    title: "Read the latest handoff",
+    description: "The latest handoff on a task: done, remaining, files, verify. Read it before continuing someone else's work.",
+    inputSchema: { task: exports_external.string() }
+  }, async ({ task }) => {
+    const pid = await projectId();
+    const j = await api2(`/v1/handoffs?project=${pid}&task=${encodeURIComponent(task)}`);
+    if (!j.text)
+      return ok(`no handoff on ${task}`, null);
+    return ok(j.text, j.handoff);
+  });
+  server.registerTool("swarm_gate_record", {
+    title: "Record a verification gate",
+    description: "Record the result of a verification gate (review, tests, security, \u2026) on a task. The rubric \u2014 what you actually checked \u2014 is required; a verdict without one is rejected. The latest run of a gate decides; failed runs stay on record and open an incident. Check `swarm_gates` for the gates this repo requires.",
+    inputSchema: {
+      task: exports_external.string().describe("task id, e.g. M1.2"),
+      gate: exports_external.string().describe("gate name, e.g. review, tests, security"),
+      verdict: exports_external.enum(["pass", "fail"]),
+      rubric: exports_external.string().describe("what was checked, concretely"),
+      evidence: exports_external.string().optional().describe("how: command output, PR link, notes")
+    }
+  }, async ({ task, gate, verdict, rubric, evidence }) => {
+    const pid = await projectId();
+    const r = await api2("/v1/gates", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        projectId: pid,
+        task,
+        gate,
+        verdict,
+        rubric,
+        evidence,
+        sessionId: SESSION
+      })
+    });
+    if (!r.ok)
+      return fail(`REFUSED: ${r.error}`);
+    return ok(`recorded ${gate} ${verdict} on ${task}`, r.run);
+  });
+  server.registerTool("swarm_gates", {
+    title: "Gate status",
+    description: "The gates this repo requires (.swarm.toml [gates] required) and, for a task, the latest verdict per gate with run history. A task is done only when every required gate's latest run is a pass.",
+    inputSchema: { task: exports_external.string().optional() }
+  }, async ({ task }) => {
+    const pid = await projectId();
+    const q = new URLSearchParams({ project: pid });
+    if (task)
+      q.set("task", task);
+    const g = await api2(`/v1/gates?${q}`);
+    const head = g.required.length ? `required: ${g.required.join(", ")}` : "no required gates declared";
+    const body = task ? (g.status ?? []).map((s) => `${s.gate}: ${s.verdict ?? "not run"}`).join(`
+`) || `no runs on ${task}` : `${g.runs.length} runs`;
+    return ok(`${head}
+${body}`, g);
+  });
   server.registerTool("swarm_claim", {
     title: "Claim a task",
     description: "Claim a task and get an isolated git worktree to work in. Fails closed if another session holds it \u2014 pick another task or coordinate. cd into the returned worktree before editing.",

package/dist/swarm.js

@@ -151,6 +151,45 @@ var WRITE_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
 var MARK = "swarm-hook";
 var isOurs = (h) => h.command.includes(MARK) || h.command.includes("/packages/hook/src/bin.ts");
 var settingsPath = () => process.env.CLAUDE_SETTINGS ?? join2(homedir2(), ".claude", "settings.json");
+var claudeJsonPath = () => process.env.CLAUDE_JSON ?? join2(homedir2(), ".claude.json");
+function loadClaudeJson() {
+  const p = claudeJsonPath();
+  if (!existsSync3(p))
+    return {};
+  try {
+    return JSON.parse(readFileSync2(p, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function saveClaudeJson(c) {
+  writeFileSync2(claudeJsonPath(), `${JSON.stringify(c, null, 2)}
+`);
+}
+function registerMcp() {
+  const c = loadClaudeJson();
+  const mcp = c.mcpServers ?? {};
+  mcp.swarm = { type: "stdio", ...mcpServerConfig() };
+  c.mcpServers = mcp;
+  saveClaudeJson(c);
+}
+function unregisterMcp() {
+  const c = loadClaudeJson();
+  const mcp = c.mcpServers ?? {};
+  if (!mcp.swarm)
+    return false;
+  delete mcp.swarm;
+  if (Object.keys(mcp).length)
+    c.mcpServers = mcp;
+  else
+    delete c.mcpServers;
+  saveClaudeJson(c);
+  return true;
+}
+function mcpRegistered() {
+  const c = loadClaudeJson();
+  return Boolean(c.mcpServers?.swarm);
+}
 var hookCommand = (event) => `${binCommand("swarm-hook")} ${event}`;
 var shimPath = () => resolveBin("swarm-hook").at(-1);
 function mcpServerConfig() {
@@ -179,10 +218,16 @@ function install() {
     added.push(ev);
   }
   s.hooks = hooks2;
-  const mcp = s.mcpServers ?? {};
-  mcp.swarm = { type: "stdio", ...mcpServerConfig() };
-  s.mcpServers = mcp;
+  const stale = s.mcpServers ?? {};
+  if (stale.swarm) {
+    delete stale.swarm;
+    if (Object.keys(stale).length)
+      s.mcpServers = stale;
+    else
+      delete s.mcpServers;
+  }
   save(s);
+  registerMcp();
   return added;
 }
 function uninstall() {
@@ -211,23 +256,22 @@ function uninstall() {
   else
     delete s.hooks;
   const mcp = s.mcpServers ?? {};
-  if (mcp.swarm) {
+  if (mcp.swarm)
     delete mcp.swarm;
-    removed++;
-  }
   if (Object.keys(mcp).length)
     s.mcpServers = mcp;
   else
     delete s.mcpServers;
   save(s);
+  if (unregisterMcp())
+    removed++;
   return removed;
 }
 function status() {
   const s = load();
   const hooks2 = s.hooks ?? {};
   const installed = Object.values(hooks2).some((l) => l.some((g) => g.hooks.some(isOurs)));
-  const mcp = Boolean(s.mcpServers?.swarm);
-  return { installed, mcp, path: settingsPath(), shim: shimPath() };
+  return { installed, mcp: mcpRegistered(), path: settingsPath(), shim: shimPath() };
 }
 
 // packages/cli/src/procs.ts
@@ -348,6 +392,13 @@ var help = `swarm \u2014 control plane for AI-agent development
   renew <task>            extend the lease;  release <task> [--force]   release + remove worktree
   claims                  list claims;  reap   release abandoned claims (keeps ones holding work)
   tasks [--ready] [--json] the repo's task source (.swarm.toml [tasks] source); --ready = claimable now
+  gate record <task> <gate> pass|fail --rubric "\u2026" [--evidence "\u2026"]   record a verification run (rubric required)
+  gate ls [task]          latest verdict per gate (and the run history for one task)
+  run --task <id> (--prompt "\u2026" | --prompt-file f) [--model m] [--permission-mode m] [--allowed-tools a,b] [--max-turns n]
+                          claim the task and spawn claude -p in its worktree; the session shows in Fleet
+  run ls | send <task|id> "text" | stop <task|id>   steer (stdin) or stop a spawned run, by pid never pattern
+  handoff <task> --done "\u2026" --remaining "\u2026" [--files a,b] [--verify "\u2026"]   leave notes for the next holder
+  resume <task>           print the latest handoff (the next session gets it automatically on start)
   res ls | acquire <name> [--owner n] [--pid n] [--port n] | release <name> [--force]
                           named singletons (ports, processes); fail-closed
   serve start [--name web] [--from-port 3400 | --port n] -- <cmd>
@@ -546,6 +597,226 @@ url: ${resolveBaseUrl()}`);
           console.log(`${c.state.padEnd(9)} ${c.task.padEnd(16)} ${(c.owner || "").padEnd(12)} ${c.worktree}`);
       break;
     }
+    case "run": {
+      await ensureDaemon({ quiet: true });
+      const proj = await api("/v1/projects", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ path: resolve3(".") })
+      });
+      const base = new SwarmClient().baseUrl;
+      const valueFlags = new Set([
+        "--task",
+        "--prompt",
+        "--prompt-file",
+        "--model",
+        "--permission-mode",
+        "--allowed-tools",
+        "--max-turns",
+        "--owner"
+      ]);
+      const positionals = [];
+      for (let i = 0;i < rest.length; i++) {
+        const a = rest[i];
+        if (valueFlags.has(a))
+          i++;
+        else if (!a.startsWith("--"))
+          positionals.push(a);
+      }
+      const flag = (n) => {
+        const i = rest.indexOf(n);
+        return i >= 0 ? rest[i + 1] : undefined;
+      };
+      const sub = positionals[0];
+      if (sub === "ls") {
+        const runs = await api(`/v1/runs?project=${proj.id}`);
+        if (json)
+          console.log(JSON.stringify(runs));
+        else if (!runs.length)
+          console.log("no live runs here");
+        else
+          for (const r2 of runs)
+            console.log(`${r2.id}  ${r2.task.padEnd(12)} pid ${String(r2.pid).padEnd(7)} ${r2.owner.padEnd(10)} ${r2.result ? `$${r2.result.costUsd.toFixed(2)} \xB7 ${r2.result.turns} turns${r2.result.isError ? " \xB7 error" : ""}` : "starting\u2026"}`);
+        break;
+      }
+      if (sub === "send" || sub === "stop") {
+        const target = positionals[1];
+        if (!target)
+          throw new Error(`usage: swarm run ${sub} <task|id>${sub === "send" ? ' "text"' : ""}`);
+        const r2 = sub === "send" ? await fetch(`${base}/v1/runs/${encodeURIComponent(target)}/send`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ text: positionals.slice(2).join(" ") })
+        }) : await fetch(`${base}/v1/runs/${encodeURIComponent(target)}`, { method: "DELETE" });
+        const j = await r2.json();
+        if (json)
+          console.log(JSON.stringify(j));
+        else if (j.ok)
+          console.log(sub === "send" ? `sent to ${target}` : `stopped ${target}`);
+        else {
+          console.error(`REFUSED: ${j.error}`);
+          process.exit(1);
+        }
+        break;
+      }
+      const task = flag("--task") ?? sub;
+      let prompt = flag("--prompt");
+      const pf = flag("--prompt-file");
+      if (!prompt && pf)
+        prompt = await Bun.file(resolve3(pf)).text();
+      if (!task || !prompt)
+        throw new Error('usage: swarm run --task <id> --prompt "\u2026" | --prompt-file f  [--model] [--permission-mode] [--allowed-tools a,b] [--max-turns n]');
+      const r = await fetch(`${base}/v1/runs`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          projectId: proj.id,
+          task,
+          prompt,
+          owner: flag("--owner") ?? process.env.USER ?? "me",
+          model: flag("--model"),
+          permissionMode: flag("--permission-mode"),
+          allowedTools: flag("--allowed-tools")?.split(",").map((t) => t.trim()).filter(Boolean),
+          maxTurns: flag("--max-turns") ? Number(flag("--max-turns")) : undefined
+        })
+      }).then((x) => x.json());
+      if (json)
+        console.log(JSON.stringify(r));
+      else if (r.ok && r.run)
+        console.log(`run ${r.run.id} on ${task} (pid ${r.run.pid})
+  worktree: ${r.run.worktree}
+  session:  ${r.run.sessionId}
+  log:      ${r.run.log}
+  steer:    swarm run send ${task} "\u2026"   stop: swarm run stop ${task}   watch: swarm tail --session ${r.run.sessionId}`);
+      else {
+        console.error(`REFUSED: ${r.error}`);
+        process.exit(1);
+      }
+      break;
+    }
+    case "handoff":
+    case "resume": {
+      await ensureDaemon({ quiet: true });
+      const task = arg();
+      if (!task)
+        throw new Error(`usage: swarm ${cmd} <task> \u2026`);
+      const proj = await api("/v1/projects", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ path: resolve3(".") })
+      });
+      if (cmd === "resume") {
+        const r2 = await fetch(`${new SwarmClient().baseUrl}/v1/handoffs?project=${proj.id}&task=${encodeURIComponent(task)}`);
+        const j = await r2.json();
+        if (json)
+          console.log(JSON.stringify(j.handoff));
+        else
+          console.log(j.text ?? `no handoff on ${task}`);
+        break;
+      }
+      const flag = (n) => {
+        const i = rest.indexOf(n);
+        return i >= 0 ? rest[i + 1] : undefined;
+      };
+      const r = await fetch(`${new SwarmClient().baseUrl}/v1/handoffs`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          projectId: proj.id,
+          task,
+          done: flag("--done"),
+          remaining: flag("--remaining"),
+          files: (flag("--files") ?? "").split(",").map((f) => f.trim()).filter(Boolean),
+          verify: flag("--verify") ?? null,
+          by: flag("--by") ?? process.env.USER ?? null,
+          sessionId: process.env.CLAUDE_SESSION_ID ?? null
+        })
+      }).then((x) => x.json());
+      if (json)
+        console.log(JSON.stringify(r));
+      else if (r.ok)
+        console.log(`handoff recorded on ${task} \u2014 the next session in its worktree sees it on start`);
+      else {
+        console.error(`REFUSED: ${r.error}`);
+        process.exit(1);
+      }
+      break;
+    }
+    case "gate": {
+      await ensureDaemon({ quiet: true });
+      const proj = await api("/v1/projects", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ path: resolve3(".") })
+      });
+      const valueFlags = new Set(["--rubric", "--evidence"]);
+      const positionals = [];
+      for (let i = 0;i < rest.length; i++) {
+        const a = rest[i];
+        if (valueFlags.has(a))
+          i++;
+        else if (!a.startsWith("--"))
+          positionals.push(a);
+      }
+      const flag = (n) => {
+        const i = rest.indexOf(n);
+        return i >= 0 ? rest[i + 1] : undefined;
+      };
+      const sub = positionals[0] ?? "ls";
+      if (sub === "record") {
+        const [, task, gate, verdict] = positionals;
+        if (!task || !gate || !verdict)
+          throw new Error('usage: swarm gate record <task> <gate> pass|fail --rubric "what was checked" [--evidence "\u2026"]');
+        const r = await fetch(`${new SwarmClient().baseUrl}/v1/gates`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            projectId: proj.id,
+            task,
+            gate,
+            verdict,
+            rubric: flag("--rubric"),
+            evidence: flag("--evidence"),
+            sessionId: process.env.CLAUDE_SESSION_ID ?? null
+          })
+        }).then((x) => x.json());
+        if (json)
+          console.log(JSON.stringify(r));
+        else if (r.ok)
+          console.log(`recorded ${gate} ${verdict} on ${task}`);
+        else {
+          console.error(`REFUSED: ${r.error}`);
+          process.exit(1);
+        }
+        break;
+      }
+      if (sub === "ls") {
+        const task = positionals[1];
+        const q = new URLSearchParams({ project: proj.id });
+        if (task)
+          q.set("task", task);
+        const g = await api(`/v1/gates?${q}`);
+        if (json)
+          console.log(JSON.stringify(g));
+        else if (task) {
+          if (!g.status?.length)
+            console.log(`no gates on ${task}${g.required.length ? ` (required: ${g.required.join(", ")})` : ""}`);
+          for (const st of g.status ?? [])
+            console.log(`${(st.verdict ?? "\u2014").padEnd(5)} ${st.gate.padEnd(12)} ${st.runs} run${st.runs === 1 ? "" : "s"}, ${st.fails} fail${st.fails === 1 ? "" : "s"}`);
+          for (const r of g.runs)
+            console.log(`  ${r.createdAt.slice(0, 16)} ${r.gate.padEnd(12)} ${r.verdict.padEnd(5)} ${r.rubric.slice(0, 70)}`);
+        } else {
+          if (g.required.length)
+            console.log(`required: ${g.required.join(", ")}`);
+          if (!g.runs.length)
+            console.log("no gate runs yet");
+          for (const r of g.runs.slice(0, 50))
+            console.log(`${r.createdAt.slice(0, 16)} ${r.task.padEnd(10)} ${r.gate.padEnd(12)} ${r.verdict.padEnd(5)} ${r.rubric.slice(0, 60)}`);
+        }
+        break;
+      }
+      throw new Error("usage: swarm gate record|ls");
+    }
     case "tasks": {
       await ensureDaemon({ quiet: true });
       const proj = await api("/v1/projects", {