dispatch-agents 0.4.0 → 0.5.0

package/README.md

@@ -49,6 +49,41 @@ npm link
 - `git` — for worktree management
 - iTerm2 (recommended) — for native tab integration via `tmux -CC`
 
+## MCP Server
+
+Dispatch includes an MCP server so Claude Code can orchestrate agents directly — no shell commands needed.
+
+### Setup
+
+After installing dispatch, register the MCP server with Claude Code:
+
+```bash
+claude mcp add --scope user dispatch node $(which dispatch-mcp)
+```
+
+This exposes 6 tools to Claude Code:
+
+| Tool | Description |
+|------|-------------|
+| `dispatch_run` | Launch an agent with a prompt (inline text, not a file) |
+| `dispatch_list` | List all running agents with status |
+| `dispatch_stop` | Stop a running agent |
+| `dispatch_resume` | Resume a stopped agent |
+| `dispatch_cleanup` | Remove worktrees and optionally branches |
+| `dispatch_logs` | Get recent output from an agent |
+
+### How it works
+
+The MCP server wraps the dispatch CLI over stdio using the [Model Context Protocol](https://modelcontextprotocol.io). When Claude Code calls `dispatch_run`, the server writes the prompt to a temp file, runs `dispatch run --prompt-file <file>`, and cleans up. Interactive agents open iTerm tabs; headless agents run in the background.
+
+### Working directory
+
+By default the MCP server uses the directory Claude Code is running in. To override, set `DISPATCH_CWD`:
+
+```bash
+claude mcp add --scope user dispatch -e DISPATCH_CWD=/path/to/repo node $(which dispatch-mcp)
+```
+
 ## Usage
 
 ### Launch an agent

package/dist/cli.js

@@ -211,6 +211,8 @@ function ensureSession() {
     execSync(
       `tmux new-session -d -s "${DISPATCH_SESSION}" -n "dispatch"`
     );
+    execSync(`tmux set -t "${DISPATCH_SESSION}" -g mouse on`);
+    execSync(`tmux set -t "${DISPATCH_SESSION}" -g history-limit 50000`);
     execSync(
       `tmux send-keys -t "${DISPATCH_SESSION}:dispatch" "# Dispatch control window" Enter`
     );
@@ -419,6 +421,9 @@ function tailFile(path) {
 
 // src/commands.ts
 var TICKET_RE = /^[A-Z]+-[0-9]+$/;
+function slugify(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40).replace(/-+$/, "");
+}
 function buildClaudeCmd(prompt, mode, wtPath, config, extraArgs) {
   let cmd = "claude";
   if (mode === "headless") cmd += " -p";
@@ -433,7 +438,7 @@ function buildClaudeCmd(prompt, mode, wtPath, config, extraArgs) {
   if (mode === "headless") {
     const promptFile = join3(wtPath, ".dispatch-prompt.txt");
     writeFileSync2(promptFile, prompt);
-    cmd += ` "$(cat '${promptFile}')"`;
+    cmd += ` < '${promptFile}'`;
   }
   return cmd;
 }
@@ -442,9 +447,9 @@ async function launchAgent(input, headless, extraArgs, skipWorktree, promptFileA
   let prompt;
   let branch;
   if (TICKET_RE.test(input)) {
-    id = input;
-    branch = input.toLowerCase();
     const ticket = await fetchLinearTicket(input);
+    id = `${input.toLowerCase()}-${slugify(ticket.title)}`;
+    branch = id;
     if (ticket.description) {
       prompt = `Linear ticket ${input}: ${ticket.title}
 
@@ -455,14 +460,13 @@ Work on this ticket. Create commits as you go. When done, push the branch.`;
       prompt = `Work on ticket ${input}: ${ticket.title}. Create commits as you go. When done, push the branch.`;
     }
   } else {
-    const suffix = String(Date.now()).slice(-6);
-    id = `task-${suffix}`;
+    id = slugify(input) || `task-${String(Date.now()).slice(-6)}`;
     branch = id;
     prompt = input;
   }
   if (nameOverride) {
-    id = nameOverride;
-    branch = nameOverride.toLowerCase();
+    id = slugify(nameOverride) || nameOverride;
+    branch = id;
   }
   if (promptFileArg) {
     if (!existsSync2(promptFileArg)) {
@@ -474,6 +478,15 @@ Work on this ticket. Create commits as you go. When done, push the branch.`;
     }
     const { readFileSync: readFileSync4 } = await import("fs");
     prompt = readFileSync4(promptFileArg, "utf-8");
+    if (!nameOverride && !TICKET_RE.test(input)) {
+      const firstLine = prompt.split("\n").find((l) => l.trim().length > 0) || "";
+      const clean = firstLine.replace(/^#+\s*/, "");
+      const derived = slugify(clean);
+      if (derived) {
+        id = derived;
+        branch = id;
+      }
+    }
   }
   if (windowExists(id)) {
     log.error(`Agent '${id}' is already running. Use 'dispatch stop ${id}' first.`);
@@ -526,6 +539,7 @@ async function cmdRun(args, config) {
   let extraArgs = "";
   let skipWorktree = false;
   let nameOverride = "";
+  let noAttach = false;
   let i = 0;
   while (i < args.length) {
     const arg = args[i];
@@ -562,6 +576,10 @@ async function cmdRun(args, config) {
         skipWorktree = true;
         i++;
         break;
+      case "--no-attach":
+        noAttach = true;
+        i++;
+        break;
       case "--name":
       case "-n":
         nameOverride = args[++i];
@@ -589,6 +607,9 @@ async function cmdRun(args, config) {
     console.log("  dispatch run HEY-837 --base main             # branch off main");
     process.exit(1);
   }
+  if (inputs.length === 0 && promptFile) {
+    inputs.push("prompt-file");
+  }
   ensureTmux();
   if (inputs.length > 1) {
     log.info(`Batch launching ${inputs.length} agents...`);
@@ -598,7 +619,7 @@ async function cmdRun(args, config) {
     await launchAgent(input, headless, extraArgs, skipWorktree, promptFile, nameOverride, config);
   }
   console.log();
-  if (!headless && inputs.length === 1) {
+  if (!headless && inputs.length === 1 && !noAttach) {
     log.info("Attaching to tmux session...");
     log.dim("  Detach with: Ctrl-B then D");
     console.log();
@@ -687,10 +708,11 @@ function cmdStop(args) {
 function cmdResume(args, config) {
   const id = args[0];
   if (!id) {
-    log.error("Usage: dispatch resume <agent-id> [--headless]");
+    log.error("Usage: dispatch resume <agent-id> [--headless] [--no-attach]");
     process.exit(1);
   }
   const headless = args.includes("--headless") || args.includes("-H");
+  const noAttach = args.includes("--no-attach");
   ensureTmux();
   const wtPath = worktreePath(id, config);
   if (!existsSync2(wtPath)) {
@@ -709,7 +731,7 @@ function cmdResume(args, config) {
       `tmux send-keys -t "${tmuxTarget(id)}" "unset CLAUDECODE && claude --continue ${modelFlag}" Enter`
     );
     log.ok(`Resumed agent: ${id} (interactive)`);
-    tmuxAttach();
+    if (!noAttach) tmuxAttach();
   } else {
     const resumePrompt = "Continue working on the task.";
     const claudeCmd = buildClaudeCmd(
@@ -858,7 +880,7 @@ function cmdSetup() {
 }
 
 // src/cli.ts
-var VERSION = "0.4.0";
+var VERSION = "0.4.1";
 function help() {
   console.log(`dispatch \u2014 Launch Claude Code agents in isolated git worktrees
 

package/dist/mcp.js

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+
+// src/mcp.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { execSync } from "child_process";
+import {
+  writeFileSync,
+  unlinkSync,
+  readFileSync,
+  existsSync
+} from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { randomBytes } from "crypto";
+function stripAnsi(str) {
+  return str.replace(/\x1b\[[0-9;]*m/g, "").replace(/\x1b\][^\x07]*\x07/g, "");
+}
+function dispatch(args) {
+  const cwd = process.env.DISPATCH_CWD || process.cwd();
+  try {
+    const output = execSync(`dispatch ${args}`, {
+      encoding: "utf-8",
+      cwd,
+      timeout: 12e4,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    return stripAnsi(output).trim();
+  } catch (e) {
+    const out = [e.stdout, e.stderr, e.message].filter(Boolean).join("\n");
+    return stripAnsi(out).trim();
+  }
+}
+function makeTempPrompt(prompt) {
+  const name = `dispatch-mcp-${randomBytes(4).toString("hex")}.md`;
+  const path = join(tmpdir(), name);
+  writeFileSync(path, prompt);
+  return path;
+}
+var server = new Server(
+  { name: "dispatch", version: "0.1.0" },
+  { capabilities: { tools: {} } }
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "dispatch_run",
+      description: "Launch a Claude Code agent in an isolated git worktree. Pass the full task prompt inline. Returns agent ID and branch name.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          prompt: {
+            type: "string",
+            description: "Full task description/prompt for the agent"
+          },
+          ticket: {
+            type: "string",
+            description: "Linear ticket ID (e.g. HEY-907). Fetches title + description if LINEAR_API_KEY is set."
+          },
+          name: {
+            type: "string",
+            description: "Agent name and branch name (kebab-case). Defaults to ticket ID or derived from prompt."
+          },
+          headless: {
+            type: "boolean",
+            description: "Run in background (fire-and-forget). Default: false (interactive)."
+          },
+          model: {
+            type: "string",
+            description: "Claude model: sonnet, opus, haiku"
+          },
+          base_branch: {
+            type: "string",
+            description: "Branch to create worktree from. Default: dev."
+          },
+          max_turns: {
+            type: "number",
+            description: "Max agentic turns (headless only)"
+          }
+        },
+        required: ["prompt"]
+      }
+    },
+    {
+      name: "dispatch_list",
+      description: "List all running dispatch agents with their status (running/idle/exited).",
+      inputSchema: { type: "object", properties: {} }
+    },
+    {
+      name: "dispatch_stop",
+      description: "Stop a running dispatch agent. Worktree and branch are preserved.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          agent_id: { type: "string", description: "Agent ID to stop" }
+        },
+        required: ["agent_id"]
+      }
+    },
+    {
+      name: "dispatch_resume",
+      description: "Resume a previously stopped agent. Picks up where it left off.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          agent_id: {
+            type: "string",
+            description: "Agent ID to resume"
+          },
+          headless: {
+            type: "boolean",
+            description: "Resume in headless mode"
+          }
+        },
+        required: ["agent_id"]
+      }
+    },
+    {
+      name: "dispatch_cleanup",
+      description: "Remove an agent's worktree and optionally its branch.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          agent_id: {
+            type: "string",
+            description: "Agent ID to clean up. Omit and set all=true for all agents."
+          },
+          all: {
+            type: "boolean",
+            description: "Clean up all worktrees"
+          },
+          delete_branch: {
+            type: "boolean",
+            description: "Also delete the git branch"
+          }
+        }
+      }
+    },
+    {
+      name: "dispatch_logs",
+      description: "Get recent output from a dispatch agent (log file or tmux capture).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          agent_id: { type: "string", description: "Agent ID" },
+          lines: {
+            type: "number",
+            description: "Number of lines to return. Default: 50."
+          }
+        },
+        required: ["agent_id"]
+      }
+    }
+  ]
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params;
+  switch (name) {
+    case "dispatch_run": {
+      const {
+        prompt,
+        ticket,
+        name: agentName,
+        headless,
+        model,
+        base_branch,
+        max_turns
+      } = args;
+      const tmpFile = makeTempPrompt(prompt);
+      try {
+        const parts = ["run"];
+        parts.push(ticket || "prompt-file");
+        parts.push(`--prompt-file "${tmpFile}"`);
+        if (agentName) parts.push(`--name "${agentName}"`);
+        if (headless) parts.push("--headless");
+        if (model) parts.push(`--model ${model}`);
+        if (base_branch) parts.push(`--base ${base_branch}`);
+        if (max_turns) parts.push(`--max-turns ${max_turns}`);
+        if (headless) parts.push("--no-attach");
+        const output = dispatch(parts.join(" "));
+        return { content: [{ type: "text", text: output }] };
+      } finally {
+        try {
+          unlinkSync(tmpFile);
+        } catch {
+        }
+      }
+    }
+    case "dispatch_list": {
+      const output = dispatch("list");
+      return {
+        content: [{ type: "text", text: output || "No agents running." }]
+      };
+    }
+    case "dispatch_stop": {
+      const { agent_id } = args;
+      const output = dispatch(`stop ${agent_id}`);
+      return { content: [{ type: "text", text: output }] };
+    }
+    case "dispatch_resume": {
+      const { agent_id, headless } = args;
+      const flags = headless ? "--headless" : "";
+      const output = dispatch(
+        `resume ${agent_id} ${flags} --no-attach`.trim()
+      );
+      return { content: [{ type: "text", text: output }] };
+    }
+    case "dispatch_cleanup": {
+      const { agent_id, all, delete_branch } = args;
+      const parts = ["cleanup"];
+      if (all) parts.push("--all");
+      else if (agent_id) parts.push(agent_id);
+      if (delete_branch) parts.push("--delete-branch");
+      const output = dispatch(parts.join(" "));
+      return { content: [{ type: "text", text: output }] };
+    }
+    case "dispatch_logs": {
+      const { agent_id, lines = 50 } = args;
+      const cwd = process.env.DISPATCH_CWD || process.cwd();
+      const logPath = join(cwd, ".worktrees", agent_id, ".dispatch.log");
+      if (existsSync(logPath)) {
+        const content = readFileSync(logPath, "utf-8");
+        const logLines = content.split("\n");
+        const lastLines = logLines.slice(-lines).join("\n");
+        return {
+          content: [{ type: "text", text: stripAnsi(lastLines) }]
+        };
+      }
+      try {
+        const output = execSync(
+          `tmux capture-pane -t "dispatch:${agent_id}" -p -S -${lines}`,
+          { encoding: "utf-8", timeout: 5e3 }
+        );
+        return {
+          content: [{ type: "text", text: stripAnsi(output).trim() }]
+        };
+      } catch {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Agent '${agent_id}' not found or no output available.`
+            }
+          ]
+        };
+      }
+    }
+    default:
+      return {
+        content: [{ type: "text", text: `Unknown tool: ${name}` }],
+        isError: true
+      };
+  }
+});
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch(console.error);

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "dispatch-agents",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Orchestrate Claude Code agents in git worktrees",
   "type": "module",
   "bin": {
-    "dispatch": "./dist/cli.js"
+    "dispatch": "./dist/cli.js",
+    "dispatch-mcp": "./dist/mcp.js"
   },
   "scripts": {
     "build": "tsup",
@@ -26,6 +27,9 @@
     "type": "git",
     "url": "https://github.com/paperMoose/dispatch.git"
   },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
   "devDependencies": {
     "tsup": "^8.0.0",
     "tsx": "^4.0.0",