dispatch-agents 0.4.1 → 0.5.1

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,8 +211,10 @@ 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 set -t "${DISPATCH_SESSION}" mouse on`);
+    execSync(`tmux set -t "${DISPATCH_SESSION}" history-limit 50000`);
+    execQuiet(`tmux set -t "${DISPATCH_SESSION}" set-titles on`);
+    execQuiet(`tmux set -t "${DISPATCH_SESSION}" set-titles-string "#W"`);
     execSync(
       `tmux send-keys -t "${DISPATCH_SESSION}:dispatch" "# Dispatch control window" Enter`
     );
@@ -241,6 +243,9 @@ function createWindow(id, cwd) {
     log.error(`Failed to create tmux window: ${err}`);
     process.exit(1);
   }
+  const target = `${DISPATCH_SESSION}:${id}`;
+  execQuiet(`tmux setw -t "${target}" allow-passthrough on`);
+  execQuiet(`tmux setw -t "${target}" automatic-rename off`);
   const countStr = execQuiet(
     `tmux list-windows -t "${DISPATCH_SESSION}" | wc -l`
   );
@@ -249,19 +254,9 @@ function createWindow(id, cwd) {
   const red = parseInt(hex.slice(0, 2), 16);
   const green = parseInt(hex.slice(2, 4), 16);
   const blue = parseInt(hex.slice(4, 6), 16);
-  const target = `${DISPATCH_SESSION}:${id}`;
-  execSync(
-    `tmux send-keys -t "${target}" "printf '\\\\033]6;1;bg;red;brightness;${red}\\\\007'" Enter`
-  );
-  execSync(
-    `tmux send-keys -t "${target}" "printf '\\\\033]6;1;bg;green;brightness;${green}\\\\007'" Enter`
-  );
-  execSync(
-    `tmux send-keys -t "${target}" "printf '\\\\033]6;1;bg;blue;brightness;${blue}\\\\007'" Enter`
-  );
   const badge = Buffer.from(id).toString("base64");
   execSync(
-    `tmux send-keys -t "${target}" "printf '\\\\033]1337;SetBadgeFormat=${badge}\\\\007'" Enter`
+    `tmux send-keys -t "${target}" "printf '\\\\033]0;${id}\\\\007\\\\033]6;1;bg;red;brightness;${red}\\\\007\\\\033]6;1;bg;green;brightness;${green}\\\\007\\\\033]6;1;bg;blue;brightness;${blue}\\\\007\\\\033]1337;SetBadgeFormat=${badge}\\\\007' && clear" Enter`
   );
   return true;
 }
@@ -294,19 +289,12 @@ function tmuxAttach(window) {
   const target = window ? `${DISPATCH_SESSION}:${window}` : DISPATCH_SESSION;
   const hasTTY = process.stdin.isTTY;
   if (hasTTY) {
-    const isIterm = process.env.TERM_PROGRAM === "iTerm.app";
-    if (isIterm) {
-      spawnSync("tmux", ["-CC", "attach", "-t", target], {
-        stdio: "inherit"
-      });
-    } else {
-      spawnSync("tmux", ["attach", "-t", target], {
-        stdio: "inherit"
-      });
-    }
+    spawnSync("tmux", ["attach", "-t", target], {
+      stdio: "inherit",
+      env: { ...process.env, TERM_PROGRAM: "dumb" }
+    });
   } else if (process.platform === "darwin") {
-    const cmd = `tmux attach -t ${target}`;
-    const script = openTerminalTabAppleScript(cmd);
+    const script = openTerminalTabAppleScript(target);
     if (script) {
       spawnSync("osascript", ["-e", script], { stdio: "pipe" });
     } else {
@@ -316,7 +304,8 @@ function tmuxAttach(window) {
     log.warn(`No TTY available. Run manually: tmux attach -t ${target}`);
   }
 }
-function openTerminalTabAppleScript(command) {
+function openTerminalTabAppleScript(target) {
+  const agentName = target.includes(":") ? target.split(":").pop() : target;
   const terminals = [
     {
       name: "iTerm2",
@@ -326,7 +315,8 @@ function openTerminalTabAppleScript(command) {
         tell current window
           create tab with default profile
           tell current session
-            write text "${command}"
+            set name to "${agentName}"
+            write text "TERM_PROGRAM=dumb tmux attach -t ${target}"
           end tell
         end tell
       end tell`
@@ -339,7 +329,7 @@ function openTerminalTabAppleScript(command) {
         tell application "System Events" to tell process "Warp"
           keystroke "t" using command down
           delay 0.3
-          keystroke "${command}"
+          keystroke "tmux attach -t ${target}"
           key code 36
         end tell
       end tell`
@@ -349,7 +339,7 @@ function openTerminalTabAppleScript(command) {
       bundleId: "com.apple.Terminal",
       script: `tell application "Terminal"
         activate
-        do script "${command}"
+        do script "tmux attach -t ${target}"
       end tell`
     }
   ];
@@ -539,6 +529,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];
@@ -575,6 +566,10 @@ async function cmdRun(args, config) {
         skipWorktree = true;
         i++;
         break;
+      case "--no-attach":
+        noAttach = true;
+        i++;
+        break;
       case "--name":
       case "-n":
         nameOverride = args[++i];
@@ -614,7 +609,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();
@@ -703,10 +698,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)) {
@@ -725,7 +721,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(

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.1",
+  "version": "0.5.1",
   "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",