dispatch-agents 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 paperMoose
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# dispatch
+
+CLI tool for orchestrating Claude Code agents in git worktrees. Dispatch work from Linear tickets or free text, run agents in named terminal tabs or headless.
+
+## The Problem
+
+You're running 15 Claude Code sessions and your terminal looks like this:
+
+```
+* Unit... | * App... | * Prod... | * DOI... | * Prof... | * Mov... | * Code...
+```
+
+Which tab is doing what? No idea.
+
+## The Solution
+
+```bash
+dispatch run HEY-837                    # Opens named tab: "HEY-837: eval improvements"
+dispatch run HEY-842 --headless         # Runs in background
+dispatch list                           # See all agents + status
+```
+
+Each agent gets:
+- Its own **git worktree** (isolated branch, no conflicts)
+- A **named tmux window** that shows as an iTerm2 tab
+- **Color-coded tabs** so you can tell them apart at a glance
+- Optional **headless mode** for fire-and-forget tasks
+
+## Install
+
+```bash
+npm install -g dispatch-agent
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/paperMoose/dispatch.git
+cd dispatch
+npm install && npm run build
+npm link
+```
+
+### Requirements
+
+- Node.js 20+
+- `tmux` — `brew install tmux`
+- `claude` — [Claude Code CLI](https://code.claude.com)
+- `git` — for worktree management
+- iTerm2 (recommended) — for native tab integration via `tmux -CC`
+
+## Usage
+
+### Launch an agent
+
+```bash
+# From a Linear ticket (fetches title + description as prompt)
+dispatch run HEY-837
+
+# Free text prompt
+dispatch run "Fix the auth bug in login.py"
+
+# Headless (background mode)
+dispatch run HEY-837 --headless
+
+# With options
+dispatch run HEY-837 --model sonnet --max-turns 10 --base main
+```
+
+### Monitor agents
+
+```bash
+# List all running agents with status
+dispatch list
+
+# Tail logs from a headless agent
+dispatch logs HEY-837
+
+# Attach to the tmux session (see all tabs)
+dispatch attach
+```
+
+### Manage agents
+
+```bash
+# Stop an agent (keeps worktree)
+dispatch stop HEY-837
+
+# Resume a stopped agent
+dispatch resume HEY-837
+
+# Clean up worktree + branch
+dispatch cleanup HEY-837
+
+# Clean up everything
+dispatch cleanup --all
+```
+
+## How It Works
+
+```
+dispatch run HEY-837
+  |
+  |-- 1. Fetch ticket from Linear (title + description)
+  |-- 2. git worktree add -b hey-837 .worktrees/hey-837 origin/dev
+  |-- 3. tmux new-window -n "HEY-837" (becomes iTerm2 tab)
+  |-- 4. Set tab color + badge
+  |-- 5. Launch Claude Code with ticket as prompt
+  |
+  v
+  Agent works in isolated worktree, commits, pushes
+```
+
+### Interactive vs Headless
+
+| | Interactive | Headless |
+|---|---|---|
+| **Tab** | Named iTerm2 tab you can watch | Detached tmux window |
+| **Interaction** | You can type into Claude Code | Fire and forget |
+| **Output** | Live in the tab | `dispatch logs <id>` |
+| **Safety** | Claude Code permission prompts | `--allowedTools` pre-approved |
+| **Use case** | Complex tasks, review as you go | Simple/well-defined tasks |
+
+## Configuration
+
+### Environment variables
+
+```bash
+export LINEAR_API_KEY="lin_api_..."      # For ticket fetching
+export DISPATCH_BASE_BRANCH="dev"        # Default base branch
+export DISPATCH_MODEL="opus"             # Default model
+```
+
+### Config file (`~/.dispatch.yml`)
+
+```yaml
+base_branch: dev
+model: opus
+max_turns: 20
+worktree_dir: .worktrees
+```
+
+## iTerm2 Integration
+
+Dispatch uses `tmux -CC` when it detects iTerm2, which maps tmux windows to native iTerm2 tabs. This means:
+
+- Each agent gets a real iTerm2 tab with a clear name
+- Tabs are color-coded to tell agents apart
+- iTerm2 badges show the ticket ID as an overlay
+- Sessions survive terminal crashes (tmux persistence)
+
+### Tab naming
+
+Disable automatic title overrides in your shell:
+
+```bash
+# Add to ~/.zshrc
+DISABLE_AUTO_TITLE="true"
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,903 @@
+#!/usr/bin/env node
+
+// src/config.ts
+import { readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+var DEFAULTS = {
+  baseBranch: "dev",
+  model: "",
+  maxTurns: "",
+  maxBudget: "",
+  allowedTools: "Bash,Read,Write,Edit,Glob,Grep,Task,WebSearch,WebFetch",
+  worktreeDir: ".worktrees",
+  claudeTimeout: 30
+};
+var KEY_MAP = {
+  base_branch: "baseBranch",
+  model: "model",
+  max_turns: "maxTurns",
+  max_budget: "maxBudget",
+  allowed_tools: "allowedTools",
+  worktree_dir: "worktreeDir",
+  claude_timeout: "claudeTimeout"
+};
+function parseSimpleYaml(content) {
+  const result = {};
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const idx = trimmed.indexOf(":");
+    if (idx === -1) continue;
+    const key = trimmed.slice(0, idx).trim();
+    let value = trimmed.slice(idx + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    result[key] = value;
+  }
+  return result;
+}
+function loadConfig(cliOverrides) {
+  const config = { ...DEFAULTS };
+  const configPath = process.env.DISPATCH_CONFIG || join(homedir(), ".dispatch.yml");
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const parsed = parseSimpleYaml(raw);
+    for (const [yamlKey, value] of Object.entries(parsed)) {
+      const configKey = KEY_MAP[yamlKey];
+      if (configKey) {
+        config[configKey] = configKey === "claudeTimeout" ? Number(value) : value;
+      }
+    }
+  } catch {
+  }
+  const envMap = [
+    ["DISPATCH_BASE_BRANCH", "baseBranch"],
+    ["DISPATCH_MODEL", "model"],
+    ["DISPATCH_MAX_TURNS", "maxTurns"],
+    ["DISPATCH_MAX_BUDGET", "maxBudget"],
+    ["DISPATCH_ALLOWED_TOOLS", "allowedTools"],
+    ["DISPATCH_CLAUDE_TIMEOUT", "claudeTimeout"]
+  ];
+  for (const [envVar, key] of envMap) {
+    const val = process.env[envVar];
+    if (val) {
+      config[key] = key === "claudeTimeout" ? Number(val) : val;
+    }
+  }
+  if (cliOverrides) {
+    for (const [key, value] of Object.entries(cliOverrides)) {
+      if (value !== void 0 && value !== "") {
+        config[key] = value;
+      }
+    }
+  }
+  return config;
+}
+
+// src/commands.ts
+import { existsSync as existsSync2, writeFileSync as writeFileSync2, readdirSync } from "fs";
+import { join as join3 } from "path";
+import { execSync as execSync2, spawnSync as spawnSync2 } from "child_process";
+
+// src/shell.ts
+import { execSync, spawnSync, spawn } from "child_process";
+import { existsSync, readFileSync as readFileSync2, writeFileSync, appendFileSync, mkdirSync } from "fs";
+import { join as join2 } from "path";
+var RED = "\x1B[0;31m";
+var GREEN = "\x1B[0;32m";
+var YELLOW = "\x1B[0;33m";
+var BLUE = "\x1B[0;34m";
+var BOLD = "\x1B[1m";
+var DIM = "\x1B[2m";
+var NC = "\x1B[0m";
+var fmt = { RED, GREEN, YELLOW, BLUE, BOLD, DIM, NC };
+var log = {
+  info: (...args) => console.log(`${BLUE}\u25B8${NC}`, ...args),
+  ok: (...args) => console.log(`${GREEN}\u2713${NC}`, ...args),
+  warn: (...args) => console.log(`${YELLOW}\u26A0${NC}`, ...args),
+  error: (...args) => console.error(`${RED}\u2717${NC}`, ...args),
+  dim: (...args) => console.log(`${DIM}${args.join(" ")}${NC}`)
+};
+var TAB_COLORS = [
+  "2E86AB",
+  "A23B72",
+  "F18F01",
+  "C73E1D",
+  "3B1F2B",
+  "44BBA4",
+  "E94F37",
+  "393E41"
+];
+var DISPATCH_SESSION = "dispatch";
+function execQuiet(cmd) {
+  try {
+    return execSync(cmd, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+  } catch {
+    return null;
+  }
+}
+function gitRoot() {
+  const root = execQuiet("git rev-parse --show-toplevel");
+  if (!root) {
+    log.error("Not inside a git repository");
+    process.exit(1);
+  }
+  return root;
+}
+function ensureWorktreeDir(config) {
+  const root = gitRoot();
+  const dir = join2(root, config.worktreeDir);
+  mkdirSync(dir, { recursive: true });
+  const gitignore = join2(root, ".gitignore");
+  const entry = `${config.worktreeDir}/`;
+  if (existsSync(gitignore)) {
+    const content = readFileSync2(gitignore, "utf-8");
+    if (!content.split("\n").includes(entry)) {
+      appendFileSync(gitignore, `
+${entry}
+`);
+    }
+  } else {
+    writeFileSync(gitignore, `${entry}
+`);
+  }
+  return dir;
+}
+function worktreePath(id, config) {
+  return join2(gitRoot(), config.worktreeDir, id);
+}
+function createWorktree(id, branch, config) {
+  const wtPath = worktreePath(id, config);
+  if (existsSync(wtPath)) {
+    log.warn(`Worktree already exists: ${wtPath}`);
+    return;
+  }
+  ensureWorktreeDir(config);
+  log.info(
+    `Creating worktree: ${BOLD}${id}${NC} (branch: ${branch} off ${config.baseBranch})`
+  );
+  execQuiet(`git fetch origin "${config.baseBranch}"`);
+  const r1 = spawnSync(
+    "git",
+    ["worktree", "add", "-b", branch, wtPath, `origin/${config.baseBranch}`],
+    { stdio: "pipe" }
+  );
+  if (r1.status !== 0) {
+    const r2 = spawnSync("git", ["worktree", "add", wtPath, branch], {
+      stdio: "pipe"
+    });
+    if (r2.status !== 0) {
+      log.error("Failed to create worktree");
+      process.exit(1);
+    }
+  }
+  log.ok(`Worktree created at ${wtPath}`);
+}
+function removeWorktree(id, config) {
+  const wtPath = worktreePath(id, config);
+  if (!existsSync(wtPath)) {
+    log.warn(`Worktree not found: ${id}`);
+    return true;
+  }
+  log.info(`Removing worktree: ${id}`);
+  const r = spawnSync("git", ["worktree", "remove", "--force", wtPath], {
+    stdio: "pipe"
+  });
+  if (r.status !== 0) {
+    log.error(
+      `Failed to remove worktree. Try: git worktree remove --force ${wtPath}`
+    );
+    return false;
+  }
+  execQuiet("git worktree prune");
+  log.ok(`Worktree removed: ${id}`);
+  return true;
+}
+function ensureTmux() {
+  const r = spawnSync("command", ["-v", "tmux"], { shell: true, stdio: "pipe" });
+  if (r.status !== 0) {
+    log.error("tmux is required. Install with: brew install tmux");
+    process.exit(1);
+  }
+}
+function ensureSession() {
+  const r = spawnSync("tmux", ["has-session", "-t", DISPATCH_SESSION], {
+    stdio: "pipe"
+  });
+  if (r.status !== 0) {
+    execSync(
+      `tmux new-session -d -s "${DISPATCH_SESSION}" -n "dispatch"`
+    );
+    execSync(
+      `tmux send-keys -t "${DISPATCH_SESSION}:dispatch" "# Dispatch control window" Enter`
+    );
+  }
+}
+function windowExists(id) {
+  const out = execQuiet(
+    `tmux list-windows -t "${DISPATCH_SESSION}" -F "#{window_name}"`
+  );
+  if (!out) return false;
+  return out.split("\n").includes(id);
+}
+function createWindow(id, cwd) {
+  if (windowExists(id)) {
+    log.warn(`Window '${id}' already exists in tmux session`);
+    return false;
+  }
+  ensureSession();
+  const r = spawnSync(
+    "tmux",
+    ["new-window", "-a", "-t", DISPATCH_SESSION, "-n", id, "-c", cwd],
+    { stdio: "pipe" }
+  );
+  if (r.status !== 0) {
+    const err = r.stderr?.toString().trim();
+    log.error(`Failed to create tmux window: ${err}`);
+    process.exit(1);
+  }
+  const countStr = execQuiet(
+    `tmux list-windows -t "${DISPATCH_SESSION}" | wc -l`
+  );
+  const count = parseInt(countStr || "1", 10);
+  const hex = TAB_COLORS[(count - 1) % TAB_COLORS.length];
+  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`
+  );
+  return true;
+}
+function tmuxTarget(id) {
+  return `${DISPATCH_SESSION}:${id}`;
+}
+function tmuxSendKeys(id, keys) {
+  execSync(`tmux send-keys -t "${tmuxTarget(id)}" ${keys}`);
+}
+function tmuxCapture(id, lines) {
+  return execQuiet(
+    `tmux capture-pane -t "${tmuxTarget(id)}" -p -S -${lines}`
+  ) || "";
+}
+function tmuxKillWindow(id) {
+  execQuiet(`tmux kill-window -t "${tmuxTarget(id)}"`);
+}
+function tmuxListWindows() {
+  return execQuiet(
+    `tmux list-windows -t "${DISPATCH_SESSION}" -F "#{window_name}|#{pane_current_command}|#{pane_current_path}|#{pane_dead}"`
+  ) || "";
+}
+function tmuxHasSession() {
+  const r = spawnSync("tmux", ["has-session", "-t", DISPATCH_SESSION], {
+    stdio: "pipe"
+  });
+  return r.status === 0;
+}
+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"
+      });
+    }
+  } else if (process.platform === "darwin") {
+    const cmd = `tmux attach -t ${target}`;
+    const script = openTerminalTabAppleScript(cmd);
+    if (script) {
+      spawnSync("osascript", ["-e", script], { stdio: "pipe" });
+    } else {
+      log.warn(`No supported terminal detected. Run manually: tmux attach -t ${target}`);
+    }
+  } else {
+    log.warn(`No TTY available. Run manually: tmux attach -t ${target}`);
+  }
+}
+function openTerminalTabAppleScript(command) {
+  const terminals = [
+    {
+      name: "iTerm2",
+      bundleId: "com.googlecode.iterm2",
+      script: `tell application "iTerm2"
+        activate
+        tell current window
+          create tab with default profile
+          tell current session
+            write text "${command}"
+          end tell
+        end tell
+      end tell`
+    },
+    {
+      name: "Warp",
+      bundleId: "dev.warp.Warp-Stable",
+      script: `tell application "Warp"
+        activate
+        tell application "System Events" to tell process "Warp"
+          keystroke "t" using command down
+          delay 0.3
+          keystroke "${command}"
+          key code 36
+        end tell
+      end tell`
+    },
+    {
+      name: "Terminal",
+      bundleId: "com.apple.Terminal",
+      script: `tell application "Terminal"
+        activate
+        do script "${command}"
+      end tell`
+    }
+  ];
+  for (const t of terminals) {
+    const r = spawnSync("osascript", [
+      "-e",
+      `tell application "System Events" to return (name of processes) contains "${t.name}"`
+    ], { stdio: "pipe" });
+    if (r.stdout?.toString().trim() === "true") {
+      return t.script;
+    }
+  }
+  return null;
+}
+async function fetchLinearTicket(ticketId) {
+  const apiKey = process.env.LINEAR_API_KEY;
+  if (!apiKey) {
+    log.warn("Could not fetch ticket details (set LINEAR_API_KEY for auto-fetch)");
+    return { title: ticketId, description: "" };
+  }
+  const teamKey = ticketId.split("-")[0];
+  const issueNum = parseInt(ticketId.split("-")[1], 10);
+  log.info(`Fetching Linear ticket: ${ticketId}`);
+  try {
+    const response = await fetch("https://api.linear.app/graphql", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: apiKey
+      },
+      body: JSON.stringify({
+        query: `{ issueSearch(filter: { number: { eq: ${issueNum} }, team: { key: { eq: "${teamKey}" } } }) { nodes { title description identifier url branchName } } }`
+      })
+    });
+    const data = await response.json();
+    const nodes = data?.data?.issueSearch?.nodes;
+    if (nodes && nodes.length > 0) {
+      log.ok(`Ticket: ${nodes[0].title}`);
+      return {
+        title: nodes[0].title || ticketId,
+        description: nodes[0].description || ""
+      };
+    }
+  } catch {
+  }
+  log.warn("Could not fetch ticket details");
+  return { title: ticketId, description: "" };
+}
+function notify(title, message) {
+  execQuiet(
+    `osascript -e 'display notification "${message}" with title "${title}" sound name "Glass"'`
+  );
+}
+function waitForClaude(id, timeout) {
+  let waited = 0;
+  while (waited < timeout) {
+    const content = tmuxCapture(id, 5);
+    if (/^\s*[>?]\s*$/m.test(content) || /╭|Welcome|claude/i.test(content)) {
+      return;
+    }
+    spawnSync("sleep", ["1"]);
+    waited++;
+  }
+  log.warn(`Claude Code may not be fully initialized (waited ${timeout}s)`);
+}
+function tailFile(path) {
+  return spawn("tail", ["-f", path], { stdio: "inherit" });
+}
+
+// src/commands.ts
+var TICKET_RE = /^[A-Z]+-[0-9]+$/;
+function buildClaudeCmd(prompt, mode, wtPath, config, extraArgs) {
+  let cmd = "claude";
+  if (mode === "headless") cmd += " -p";
+  if (config.model) cmd += ` --model ${config.model}`;
+  if (mode === "headless") {
+    cmd += ` --allowedTools "${config.allowedTools}"`;
+    if (config.maxTurns) cmd += ` --max-turns ${config.maxTurns}`;
+    if (config.maxBudget) cmd += ` --max-budget-usd ${config.maxBudget}`;
+    cmd += " --output-format json";
+  }
+  if (extraArgs) cmd += ` ${extraArgs}`;
+  if (mode === "headless") {
+    const promptFile = join3(wtPath, ".dispatch-prompt.txt");
+    writeFileSync2(promptFile, prompt);
+    cmd += ` "$(cat '${promptFile}')"`;
+  }
+  return cmd;
+}
+async function launchAgent(input, headless, extraArgs, skipWorktree, promptFileArg, nameOverride, config) {
+  let id;
+  let prompt;
+  let branch;
+  if (TICKET_RE.test(input)) {
+    id = input;
+    branch = input.toLowerCase();
+    const ticket = await fetchLinearTicket(input);
+    if (ticket.description) {
+      prompt = `Linear ticket ${input}: ${ticket.title}
+
+${ticket.description}
+
+Work on this ticket. Create commits as you go. When done, push the branch.`;
+    } else {
+      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}`;
+    branch = id;
+    prompt = input;
+  }
+  if (nameOverride) {
+    id = nameOverride;
+    branch = nameOverride.toLowerCase();
+  }
+  if (promptFileArg) {
+    if (!existsSync2(promptFileArg)) {
+      log.error(`Prompt file not found: ${promptFileArg}`);
+      return;
+    }
+    if (TICKET_RE.test(input)) {
+      log.warn(`Ticket prompt for ${input} overridden by --prompt-file`);
+    }
+    const { readFileSync: readFileSync3 } = await import("fs");
+    prompt = readFileSync3(promptFileArg, "utf-8");
+  }
+  if (windowExists(id)) {
+    log.error(`Agent '${id}' is already running. Use 'dispatch stop ${id}' first.`);
+    return;
+  }
+  let wtPath;
+  if (skipWorktree) {
+    wtPath = gitRoot();
+  } else {
+    createWorktree(id, branch, config);
+    wtPath = worktreePath(id, config);
+  }
+  createWindow(id, wtPath);
+  const mode = headless ? "headless" : "interactive";
+  const claudeCmd = buildClaudeCmd(prompt, mode, wtPath, config, extraArgs);
+  if (mode === "interactive") {
+    const modelFlag = config.model ? `--model ${config.model}` : "";
+    execSync2(
+      `tmux send-keys -t "${tmuxTarget(id)}" "unset CLAUDECODE && claude ${modelFlag}" Enter`
+    );
+    waitForClaude(id, config.claudeTimeout);
+    const pf = join3(wtPath, ".dispatch-prompt.txt");
+    writeFileSync2(pf, prompt);
+    const bufName = `dispatch-${id.replace(/[^a-zA-Z0-9]/g, "-")}`;
+    execSync2(`tmux load-buffer -b "${bufName}" "${pf}"`);
+    execSync2(
+      `tmux paste-buffer -b "${bufName}" -t "${tmuxTarget(id)}"`
+    );
+    execQuiet(`tmux delete-buffer -b "${bufName}"`);
+    execSync2(`tmux send-keys -t "${tmuxTarget(id)}" Enter`);
+  } else {
+    const logFile = join3(wtPath, ".dispatch.log");
+    execSync2(
+      `tmux send-keys -t "${tmuxTarget(id)}" "unset CLAUDECODE && ${claudeCmd} 2>&1 | tee -a ${logFile}; dispatch _notify-done ${id}" Enter`
+    );
+  }
+  console.log();
+  log.ok(`Agent ${fmt.BOLD}${id}${fmt.NC} launched (${mode})`);
+  log.dim(`  Worktree: ${wtPath}`);
+  log.dim(`  Branch:   ${branch}`);
+  if (headless) {
+    log.dim(`  Logs:     dispatch logs ${id}`);
+    log.dim(`  Stop:     dispatch stop ${id}`);
+  }
+}
+async function cmdRun(args, config) {
+  const inputs = [];
+  let headless = false;
+  let promptFile = "";
+  let extraArgs = "";
+  let skipWorktree = false;
+  let nameOverride = "";
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    switch (arg) {
+      case "--headless":
+      case "-H":
+        headless = true;
+        i++;
+        break;
+      case "--model":
+      case "-m":
+        config.model = args[++i];
+        i++;
+        break;
+      case "--max-turns":
+        config.maxTurns = args[++i];
+        i++;
+        break;
+      case "--max-budget":
+        config.maxBudget = args[++i];
+        i++;
+        break;
+      case "--base":
+      case "-b":
+        config.baseBranch = args[++i];
+        i++;
+        break;
+      case "--prompt-file":
+      case "-f":
+        promptFile = args[++i];
+        i++;
+        break;
+      case "--no-worktree":
+        skipWorktree = true;
+        i++;
+        break;
+      case "--name":
+      case "-n":
+        nameOverride = args[++i];
+        i++;
+        break;
+      default:
+        if (arg.startsWith("--")) {
+          extraArgs += ` ${arg}`;
+        } else {
+          inputs.push(arg);
+        }
+        i++;
+        break;
+    }
+  }
+  if (inputs.length === 0 && !promptFile) {
+    log.error("Usage: dispatch run <ticket|prompt> [ticket2 ...] [options]");
+    console.log();
+    console.log("  dispatch run HEY-837                         # from Linear ticket");
+    console.log("  dispatch run HEY-837 HEY-838 HEY-839        # batch launch");
+    console.log("  dispatch run HEY-837 --headless              # run in background");
+    console.log('  dispatch run "Fix the auth bug"               # free text prompt');
+    console.log("  dispatch run HEY-837 --model sonnet          # specific model");
+    console.log("  dispatch run HEY-837 --max-turns 10          # limit turns");
+    console.log("  dispatch run HEY-837 --base main             # branch off main");
+    process.exit(1);
+  }
+  ensureTmux();
+  if (inputs.length > 1) {
+    log.info(`Batch launching ${inputs.length} agents...`);
+    console.log();
+  }
+  for (const input of inputs) {
+    await launchAgent(input, headless, extraArgs, skipWorktree, promptFile, nameOverride, config);
+  }
+  console.log();
+  if (!headless && inputs.length === 1) {
+    log.info("Attaching to tmux session...");
+    log.dim("  Detach with: Ctrl-B then D");
+    console.log();
+    tmuxAttach();
+  } else if (inputs.length > 1) {
+    log.ok(`All agents launched. Use ${fmt.BOLD}dispatch attach${fmt.NC} to view tabs.`);
+  }
+}
+function cmdList(config) {
+  ensureTmux();
+  if (!tmuxHasSession()) {
+    log.info("No dispatch session running");
+    return;
+  }
+  console.log();
+  console.log(`${fmt.BOLD}Running Agents${fmt.NC}`);
+  console.log(
+    `${fmt.DIM}\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500${fmt.NC}`
+  );
+  const root = execQuiet("git rev-parse --show-toplevel") || "";
+  const lines = tmuxListWindows();
+  for (const line of lines.split("\n")) {
+    if (!line) continue;
+    const [name, cmd, path, dead] = line.split("|");
+    if (name === "dispatch") continue;
+    let statusIcon;
+    let statusText;
+    if (dead === "1") {
+      statusIcon = `${fmt.RED}\u25CF${fmt.NC}`;
+      statusText = "exited";
+    } else if (cmd === "claude" || cmd === "node") {
+      statusIcon = `${fmt.GREEN}\u25CF${fmt.NC}`;
+      statusText = "running";
+    } else {
+      statusIcon = `${fmt.YELLOW}\u25CF${fmt.NC}`;
+      statusText = "idle";
+    }
+    const shortPath = root && path.startsWith(root + "/") ? path.slice(root.length + 1) : path;
+    console.log(
+      `  ${statusIcon} ${fmt.BOLD}${name}${fmt.NC}  ${fmt.DIM}(${statusText})${fmt.NC}`
+    );
+    console.log(`    ${fmt.DIM}path: ${shortPath}${fmt.NC}`);
+  }
+  console.log();
+}
+function cmdLogs(args, config) {
+  const id = args[0];
+  if (!id) {
+    log.error("Usage: dispatch logs <agent-id>");
+    process.exit(1);
+  }
+  const wtPath = worktreePath(id, config);
+  const logFile = join3(wtPath, ".dispatch.log");
+  if (existsSync2(logFile)) {
+    log.info(`Tailing log: ${logFile}`);
+    const child = tailFile(logFile);
+    process.on("SIGINT", () => {
+      child.kill();
+      process.exit(0);
+    });
+    child.on("exit", () => process.exit(0));
+  } else if (windowExists(id)) {
+    log.info("Capturing output from tmux pane...");
+    console.log(tmuxCapture(id, 100));
+  } else {
+    log.error(`Agent '${id}' not found`);
+    process.exit(1);
+  }
+}
+function cmdStop(args) {
+  const id = args[0];
+  if (!id) {
+    log.error("Usage: dispatch stop <agent-id>");
+    process.exit(1);
+  }
+  if (!windowExists(id)) {
+    log.warn(`Agent '${id}' is not running`);
+    return;
+  }
+  log.info(`Stopping agent: ${id}`);
+  tmuxSendKeys(id, "C-c");
+  spawnSync2("sleep", ["1"]);
+  tmuxKillWindow(id);
+  log.ok(`Agent stopped: ${id}`);
+}
+function cmdResume(args, config) {
+  const id = args[0];
+  if (!id) {
+    log.error("Usage: dispatch resume <agent-id> [--headless]");
+    process.exit(1);
+  }
+  const headless = args.includes("--headless") || args.includes("-H");
+  ensureTmux();
+  const wtPath = worktreePath(id, config);
+  if (!existsSync2(wtPath)) {
+    log.error(`Worktree not found for '${id}'. Nothing to resume.`);
+    process.exit(1);
+  }
+  if (windowExists(id)) {
+    log.warn(`Agent '${id}' is already running. Attaching...`);
+    tmuxAttach();
+    return;
+  }
+  createWindow(id, wtPath);
+  if (!headless) {
+    const modelFlag = config.model ? `--model ${config.model}` : "";
+    execSync2(
+      `tmux send-keys -t "${tmuxTarget(id)}" "unset CLAUDECODE && claude --continue ${modelFlag}" Enter`
+    );
+    log.ok(`Resumed agent: ${id} (interactive)`);
+    tmuxAttach();
+  } else {
+    const resumePrompt = "Continue working on the task.";
+    const claudeCmd = buildClaudeCmd(
+      resumePrompt,
+      "headless",
+      wtPath,
+      config,
+      "--continue"
+    );
+    const logFile = join3(wtPath, ".dispatch.log");
+    execSync2(
+      `tmux send-keys -t "${tmuxTarget(id)}" "unset CLAUDECODE && ${claudeCmd} 2>&1 | tee -a ${logFile}; dispatch _notify-done ${id}" Enter`
+    );
+    log.ok(`Resumed agent: ${id} (headless)`);
+  }
+}
+function cmdCleanup(args, config) {
+  let id = "";
+  let all = false;
+  let deleteBranch = false;
+  for (const arg of args) {
+    switch (arg) {
+      case "--all":
+        all = true;
+        break;
+      case "--delete-branch":
+        deleteBranch = true;
+        break;
+      default:
+        id = arg;
+        break;
+    }
+  }
+  if (all) {
+    log.info("Cleaning up all worktrees...");
+    const root = gitRoot();
+    const wtDir = join3(root, config.worktreeDir);
+    if (!existsSync2(wtDir)) {
+      log.info("No worktrees to clean up");
+      return;
+    }
+    let entries;
+    try {
+      entries = readdirSync(wtDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+    } catch {
+      log.info("No worktrees to clean up");
+      return;
+    }
+    for (const name of entries) {
+      if (windowExists(name)) {
+        cmdStop([name]);
+      }
+      removeWorktree(name, config);
+      if (deleteBranch) {
+        const r = spawnSync2("git", ["branch", "-D", name], { stdio: "pipe" });
+        if (r.status === 0) {
+          log.ok(`Deleted branch: ${name}`);
+        } else {
+          log.warn(`Branch not found: ${name}`);
+        }
+      }
+    }
+  } else if (id) {
+    if (windowExists(id)) {
+      cmdStop([id]);
+    }
+    removeWorktree(id, config);
+    if (deleteBranch) {
+      const r = spawnSync2("git", ["branch", "-D", id], { stdio: "pipe" });
+      if (r.status === 0) {
+        log.ok(`Deleted branch: ${id}`);
+      } else {
+        log.warn(`Branch not found: ${id}`);
+      }
+    }
+  } else {
+    log.error("Usage: dispatch cleanup <agent-id> | --all [--delete-branch]");
+    process.exit(1);
+  }
+}
+function cmdAttach(args) {
+  ensureTmux();
+  if (!tmuxHasSession()) {
+    log.error("No dispatch session running");
+    process.exit(1);
+  }
+  const window = args[0] || void 0;
+  tmuxAttach(window);
+}
+function cmdNotifyDone(args) {
+  const agentId = args[0] || "unknown";
+  notify("Dispatch", `Agent ${agentId} finished`);
+  log.ok(`Agent ${agentId} completed`);
+}
+
+// src/cli.ts
+var VERSION = "0.3.0";
+function help() {
+  console.log(`dispatch \u2014 Orchestrate Claude Code agents in git worktrees
+
+Usage:
+  dispatch run <ticket|prompt> [more...] [options]  Launch agent(s)
+  dispatch list                                     Show running agents
+  dispatch logs <id>                                Tail agent output
+  dispatch stop <id>                                Stop an agent
+  dispatch resume <id> [--headless]                 Resume a stopped agent
+  dispatch cleanup <id> | --all [--delete-branch]    Remove worktree(s)
+  dispatch attach                                   Attach to tmux session
+
+Run Options:
+  --headless, -H          Run in background (no interactive tab)
+  --model, -m <model>     Claude model (sonnet, opus, etc.)
+  --max-turns <n>         Limit agent turns (headless only)
+  --max-budget <usd>      Cap spending (headless only)
+  --base, -b <branch>     Base branch for worktree (default: dev)
+  --prompt-file, -f <file> Load prompt from file
+  --name, -n <name>       Override agent name and branch (e.g., HEY-879)
+  --no-worktree           Run in current directory (no worktree)
+
+Examples:
+  dispatch run HEY-837                      Interactive, from Linear ticket
+  dispatch run HEY-837 --headless           Background mode
+  dispatch run HEY-837 HEY-838 HEY-839     Batch launch (multiple agents)
+  dispatch run "Fix the auth bug"           Free text prompt
+  dispatch run HEY-837 -m sonnet            Use Sonnet model
+  dispatch run HEY-837 --max-turns 10       Limit to 10 turns
+
+Environment:
+  LINEAR_API_KEY          Linear API key for ticket fetching
+  DISPATCH_BASE_BRANCH   Default base branch (default: dev)
+  DISPATCH_MODEL         Default model
+  DISPATCH_CONFIG        Config file path (default: ~/.dispatch.yml)
+
+Config (~/.dispatch.yml):
+  base_branch: dev
+  model: opus
+  max_turns: 20
+  claude_timeout: 30
+  worktree_dir: .worktrees`);
+}
+async function main() {
+  const args = process.argv.slice(2);
+  const cmd = args[0] || "help";
+  const rest = args.slice(1);
+  const config = loadConfig();
+  switch (cmd) {
+    case "run":
+      await cmdRun(rest, config);
+      break;
+    case "list":
+    case "ls":
+      cmdList(config);
+      break;
+    case "logs":
+      cmdLogs(rest, config);
+      break;
+    case "stop":
+      cmdStop(rest);
+      break;
+    case "resume":
+      cmdResume(rest, config);
+      break;
+    case "cleanup":
+      cmdCleanup(rest, config);
+      break;
+    case "attach":
+      cmdAttach(rest);
+      break;
+    case "_notify-done":
+      cmdNotifyDone(rest);
+      break;
+    case "version":
+    case "-v":
+    case "--version":
+      console.log(`dispatch v${VERSION}`);
+      break;
+    case "help":
+    case "-h":
+    case "--help":
+      help();
+      break;
+    default:
+      console.error(`\x1B[0;31m\u2717\x1B[0m Unknown command: ${cmd}`);
+      console.log();
+      help();
+      process.exit(1);
+  }
+}
+main().catch((err) => {
+  console.error(`\x1B[0;31m\u2717\x1B[0m ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "dispatch-agents",
+  "version": "0.3.0",
+  "description": "Orchestrate Claude Code agents in git worktrees",
+  "type": "module",
+  "bin": {
+    "dispatch": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "node --import tsx --test tests/*.test.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "claude",
+    "agent",
+    "tmux",
+    "worktree",
+    "dispatch"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paperMoose/dispatch.git"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.4.0"
+  }
+}