dispatch-agents 0.3.0 → 0.4.0

package/README.md

@@ -29,7 +29,7 @@ Each agent gets:
 ## Install
 
 ```bash
-npm install -g dispatch-agent
+npm install -g dispatch-agents
 ```
 
 Or from source:

package/dist/cli.js

@@ -77,8 +77,9 @@ function loadConfig(cliOverrides) {
 }
 
 // src/commands.ts
-import { existsSync as existsSync2, writeFileSync as writeFileSync2, readdirSync } from "fs";
+import { existsSync as existsSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2, appendFileSync as appendFileSync2, readdirSync } from "fs";
 import { join as join3 } from "path";
+import { homedir as homedir2 } from "os";
 import { execSync as execSync2, spawnSync as spawnSync2 } from "child_process";
 
 // src/shell.ts
@@ -471,8 +472,8 @@ Work on this ticket. Create commits as you go. When done, push the branch.`;
     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");
+    const { readFileSync: readFileSync4 } = await import("fs");
+    prompt = readFileSync4(promptFileArg, "utf-8");
   }
   if (windowExists(id)) {
     log.error(`Agent '${id}' is already running. Use 'dispatch stop ${id}' first.`);
@@ -803,51 +804,131 @@ function cmdNotifyDone(args) {
   notify("Dispatch", `Agent ${agentId} finished`);
   log.ok(`Agent ${agentId} completed`);
 }
+var CLAUDE_MD_SNIPPET = `
+## Dispatch (multi-agent orchestration)
+
+Launch Claude Code agents in isolated git worktrees. Each agent gets its own branch, so it can make changes without affecting your working tree or other agents. Agents run inside tmux \u2014 interactive mode to watch/guide, headless for fire-and-forget.
+
+**When to use:** Hand off well-defined tasks (Linear tickets, bug fixes, features) to a parallel agent while you keep working. Avoid dispatching two agents to the same files \u2014 they'll create merge conflicts.
+
+\`\`\`bash
+# Launch agents
+dispatch run HEY-123                                  # From Linear ticket (auto-fetches title + description)
+dispatch run "Fix the auth bug" --name HEY-879        # Free text with custom branch name (hey-879)
+dispatch run HEY-123 --headless                       # Background \u2014 check with: dispatch logs HEY-123
+dispatch run HEY-123 -m sonnet --max-turns 20         # Sonnet, 20 turn limit
+dispatch run HEY-123 HEY-124 HEY-125                 # Batch launch in parallel
+
+# Monitor and interact
+dispatch list                                         # Status: green=running, yellow=idle, red=exited
+dispatch attach HEY-123                               # Jump to agent's terminal (auto-opens tab if no TTY)
+dispatch logs HEY-123                                 # Tail headless agent output
+
+# Lifecycle
+dispatch stop HEY-123                                 # Interrupt agent (worktree preserved)
+dispatch resume HEY-123                               # Pick up where it left off (--continue)
+dispatch cleanup HEY-123 --delete-branch              # Remove worktree + branch
+dispatch cleanup --all --delete-branch                # Clean up everything
+\`\`\`
+
+**Key flags:** \`--name/-n\` sets branch name, \`--model/-m\` picks model, \`--headless/-H\` for background, \`--prompt-file/-f\` for long prompts, \`--base/-b\` to branch off something other than dev.
+
+Config: \`~/.dispatch.yml\` (base_branch, model, max_turns, max_budget, worktree_dir, claude_timeout).
+Requires: tmux, claude CLI, git.
+`;
+function cmdSetup() {
+  const claudeMdPath = join3(homedir2(), ".claude", "CLAUDE.md");
+  if (existsSync2(claudeMdPath)) {
+    const content = readFileSync3(claudeMdPath, "utf-8");
+    if (content.includes("dispatch run") || content.includes("Dispatch (multi-agent")) {
+      log.warn("Dispatch section already exists in ~/.claude/CLAUDE.md");
+      log.info("To update it, remove the existing Dispatch section and run setup again.");
+      return;
+    }
+    appendFileSync2(claudeMdPath, "\n" + CLAUDE_MD_SNIPPET);
+    log.ok("Added dispatch section to ~/.claude/CLAUDE.md");
+  } else {
+    const claudeDir = join3(homedir2(), ".claude");
+    if (!existsSync2(claudeDir)) {
+      spawnSync2("mkdir", ["-p", claudeDir]);
+    }
+    writeFileSync2(claudeMdPath, CLAUDE_MD_SNIPPET.trimStart());
+    log.ok("Created ~/.claude/CLAUDE.md with dispatch section");
+  }
+}
 
 // src/cli.ts
-var VERSION = "0.3.0";
+var VERSION = "0.4.0";
 function help() {
-  console.log(`dispatch \u2014 Orchestrate Claude Code agents in git worktrees
+  console.log(`dispatch \u2014 Launch Claude Code agents in isolated git worktrees
+
+Each agent gets its own branch and worktree, so it can make changes without
+affecting your working tree or other agents. Agents run inside tmux \u2014 use
+interactive mode to watch and guide them, or headless for fire-and-forget.
 
-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
+Commands:
+  dispatch run <ticket|prompt> [options]   Launch an agent
+  dispatch list                            Show all running agents with status
+  dispatch logs <id>                       Tail a headless agent's output
+  dispatch stop <id>                       Send Ctrl-C and kill the tmux window
+  dispatch resume <id> [--headless]        Restart a stopped agent (keeps context)
+  dispatch cleanup <id> [--delete-branch]  Remove worktree (and optionally branch)
+  dispatch cleanup --all [--delete-branch] Remove all worktrees
+  dispatch attach [id]                     Open tmux session (or jump to specific agent)
+  dispatch setup                           Add dispatch docs to ~/.claude/CLAUDE.md
 
 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)
+  --headless, -H            Fire-and-forget mode (no interactive terminal)
+  --model, -m <model>       Claude model: sonnet, opus, haiku (default: from config)
+  --name, -n <name>         Set agent name and branch (default: ticket ID or task-{random})
+  --max-turns <n>           Limit agentic turns before stopping (headless only)
+  --max-budget <usd>        Cap spending in USD (headless only)
+  --base, -b <branch>       Branch to create worktree from (default: dev)
+  --prompt-file, -f <file>  Load prompt from a file instead of CLI arg
+  --no-worktree             Run in current directory (no isolation)
+
+Lifecycle:
+  1. run    \u2014 Creates worktree + branch, opens tmux window, starts Claude Code
+  2. work   \u2014 Agent reads codebase, makes changes, commits, pushes, creates PRs
+  3. attach \u2014 View/interact with the agent (auto-opens terminal tab if no TTY)
+  4. stop   \u2014 Interrupt the agent (worktree and branch preserved)
+  5. resume \u2014 Pick up where it left off (Claude --continue)
+  6. cleanup \u2014 Remove worktree when done (--delete-branch to also delete the branch)
+
+Input Types:
+  Linear ticket    dispatch run HEY-837              Fetches title + description from Linear
+  Free text        dispatch run "Fix the auth bug"   Uses your prompt directly
+  Prompt file      dispatch run X -f prompt.txt      Loads prompt from file (good for long prompts)
 
 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
+  dispatch run HEY-837                                  # Interactive, from Linear ticket
+  dispatch run HEY-837 --headless                       # Background \u2014 check with: dispatch logs HEY-837
+  dispatch run HEY-837 HEY-838 HEY-839                 # Batch launch 3 agents in parallel
+  dispatch run "Fix the auth bug" --name HEY-879        # Free text with custom branch name
+  dispatch run HEY-837 -m sonnet --max-turns 20         # Sonnet model, 20 turn limit
+  dispatch attach HEY-837                               # Jump to agent's terminal
+  dispatch list                                         # See what's running
+  dispatch cleanup --all --delete-branch                # Clean everything up
+
+Tips:
+  - Each agent works on its own branch \u2014 avoid dispatching two agents to the same files
+  - Use --name to get meaningful branch names (e.g., --name HEY-879 creates branch hey-879)
+  - Interactive mode lets you guide the agent; headless is for well-defined tasks
+  - Works from inside Claude Code sessions (agents launch in separate terminals)
+  - Use dispatch list to check status: green = running, yellow = idle, red = exited
 
 Environment:
-  LINEAR_API_KEY          Linear API key for ticket fetching
+  LINEAR_API_KEY         Linear API key for auto-fetching ticket details
   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`);
+  base_branch: dev        # Branch to create worktrees from
+  model: opus             # Default Claude model
+  max_turns: 20           # Default max turns for headless
+  claude_timeout: 30      # Seconds to wait for Claude to start
+  worktree_dir: .worktrees  # Where worktrees are created`);
 }
 async function main() {
   const args = process.argv.slice(2);
@@ -877,6 +958,9 @@ async function main() {
     case "attach":
       cmdAttach(rest);
       break;
+    case "setup":
+      cmdSetup();
+      break;
     case "_notify-done":
       cmdNotifyDone(rest);
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dispatch-agents",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Orchestrate Claude Code agents in git worktrees",
   "type": "module",
   "bin": {