@groupchatai/claude-runner 0.4.0 → 0.4.2

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { spawn } from "child_process";
-import { readFileSync } from "fs";
+import { spawn, execFileSync } from "child_process";
+import { readFileSync, readdirSync, statSync, writeFileSync, existsSync, rmSync } from "fs";
 import path from "path";
 var API_URL = "https://groupchat.ai";
 var CONVEX_URL = "https://fantastic-jay-464.convex.cloud";
@@ -116,7 +116,7 @@ Due: ${new Date(detail.task.dueDate).toLocaleDateString()}`);
       "- NEVER run `gh pr merge`. Do NOT merge any PR.",
       "- NEVER run `gh pr close`. Do NOT close any PR.",
       "- NEVER run `git push --force` or `git push -f`. No force pushes.",
-      "- When you are done, provide a clear summary of what you accomplished including the PR URL and branch name."
+      "- When you are done, provide a clear summary of what you accomplished."
     ].join("\n")
   );
   return parts.join("\n");
@@ -240,7 +240,7 @@ var ALLOWED_TOOLS = [
   "TodoWrite",
   "NotebookEdit"
 ];
-function spawnClaudeCode(prompt, config, runOptions, resumeSessionId) {
+function spawnClaudeCode(prompt, config, runOptions, resumeSessionId, cwdOverride) {
   const format = config.verbose ? "stream-json" : "json";
   const args = [];
   if (resumeSessionId) {
@@ -262,9 +262,8 @@ function spawnClaudeCode(prompt, config, runOptions, resumeSessionId) {
     args.push("--model", model);
   }
   const child = spawn("claude", args, {
-    cwd: config.workDir,
-    stdio: ["ignore", "pipe", "pipe"],
-    env: { ...process.env }
+    cwd: cwdOverride ?? config.workDir,
+    stdio: ["ignore", "pipe", "pipe"]
   });
   const pid = child.pid ?? 0;
   const output = new Promise((resolve, reject) => {
@@ -446,7 +445,202 @@ function runShellCommand(cmd, args, cwd) {
 }
 var sessionCache = /* @__PURE__ */ new Map();
 var runCounter = 0;
-async function processRun(client, run, config) {
+var WORKTREE_DIR = ".agent-worktrees";
+var WORKTREE_PREFIX = "task-";
+function worktreeNameForTask(taskId) {
+  return `${WORKTREE_PREFIX}${taskId.replace(/[^a-zA-Z0-9_-]/g, "-").slice(-12)}`;
+}
+function execGit(args, cwd) {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: "pipe" }).trim();
+}
+function getDefaultBranch(repoDir) {
+  try {
+    const out = execGit(["symbolic-ref", "refs/remotes/origin/HEAD", "--short"], repoDir);
+    return out.replace("origin/", "");
+  } catch {
+    return "main";
+  }
+}
+function createWorktree(repoDir, taskId) {
+  const name = worktreeNameForTask(taskId);
+  const branchName = `agent/${name}-${Date.now()}`;
+  const worktreeBase = path.join(repoDir, WORKTREE_DIR);
+  const worktreePath = path.join(worktreeBase, name);
+  if (existsSync(worktreePath)) {
+    return worktreePath;
+  }
+  const baseBranch = getDefaultBranch(repoDir);
+  try {
+    execGit(["fetch", "origin", baseBranch, "--quiet"], repoDir);
+  } catch {
+  }
+  execGit(["worktree", "add", "-b", branchName, worktreePath, `origin/${baseBranch}`], repoDir);
+  writeFileSync(path.join(worktreePath, ".agent-branch"), branchName, "utf-8");
+  return worktreePath;
+}
+async function listOurWorktrees(workDir) {
+  const worktreeDir = path.join(workDir, WORKTREE_DIR);
+  let entries;
+  try {
+    entries = readdirSync(worktreeDir).filter((e) => e.startsWith(WORKTREE_PREFIX));
+  } catch {
+    return [];
+  }
+  const results = [];
+  for (const name of entries) {
+    const wtPath = path.join(worktreeDir, name);
+    let branch = `agent/${name}`;
+    try {
+      branch = readFileSync(path.join(wtPath, ".agent-branch"), "utf-8").trim();
+    } catch {
+    }
+    let ageMs = 0;
+    let age = "unknown";
+    try {
+      const stat = statSync(wtPath);
+      ageMs = Date.now() - stat.mtimeMs;
+      if (ageMs < 6e4) age = "just now";
+      else if (ageMs < 36e5) age = `${Math.floor(ageMs / 6e4)}m ago`;
+      else if (ageMs < 864e5) age = `${Math.floor(ageMs / 36e5)}h ago`;
+      else age = `${Math.floor(ageMs / 864e5)}d ago`;
+    } catch {
+    }
+    let isMerged = false;
+    try {
+      const merged = await runShellCommand(
+        "git",
+        ["branch", "--merged", "main", "--list", branch],
+        workDir
+      );
+      isMerged = merged.trim().length > 0;
+    } catch {
+    }
+    let hasUnpushed = false;
+    try {
+      const log = await runShellCommand(
+        "git",
+        ["log", `origin/${branch}..${branch}`, "--oneline"],
+        wtPath
+      );
+      hasUnpushed = log.trim().length > 0;
+    } catch {
+      try {
+        const log = await runShellCommand(
+          "git",
+          ["log", `origin/main..${branch}`, "--oneline"],
+          workDir
+        );
+        hasUnpushed = log.trim().length > 0;
+      } catch {
+      }
+    }
+    results.push({
+      name,
+      path: wtPath,
+      branch,
+      age,
+      ageMs,
+      isMerged,
+      hasUnpushed: hasUnpushed && !isMerged,
+      safeToRemove: isMerged || !hasUnpushed && ageMs > 36e5
+    });
+  }
+  return results;
+}
+async function removeWorktree(workDir, info) {
+  try {
+    await runShellCommand("git", ["worktree", "remove", info.path, "--force"], workDir);
+    try {
+      await runShellCommand("git", ["branch", "-D", info.branch], workDir);
+    } catch {
+    }
+    return true;
+  } catch (err) {
+    console.error(`  Failed to remove ${info.name}: ${err instanceof Error ? err.message : err}`);
+    return false;
+  }
+}
+function removeWorktreeSimple(repoDir, worktreePath) {
+  let branchName;
+  try {
+    branchName = readFileSync(path.join(worktreePath, ".agent-branch"), "utf-8").trim();
+  } catch {
+  }
+  try {
+    execGit(["worktree", "remove", worktreePath, "--force"], repoDir);
+  } catch {
+    try {
+      if (existsSync(worktreePath)) rmSync(worktreePath, { recursive: true, force: true });
+      execGit(["worktree", "prune"], repoDir);
+    } catch {
+    }
+  }
+  if (branchName) {
+    try {
+      execGit(["branch", "-D", branchName], repoDir);
+    } catch {
+    }
+  }
+}
+async function startupSweep(workDir) {
+  const worktrees = await listOurWorktrees(workDir);
+  if (worktrees.length === 0) return;
+  const safe = worktrees.filter((w) => w.safeToRemove);
+  const unsafe = worktrees.filter((w) => !w.safeToRemove);
+  if (safe.length > 0) {
+    console.log(`\u{1F9F9} Cleaning up ${safe.length} stale worktree(s)\u2026`);
+    for (const wt of safe) {
+      const label = wt.isMerged ? "merged" : "stale";
+      const ok = await removeWorktree(workDir, wt);
+      if (ok) console.log(`   \u2705 Removed ${wt.name} (${label}, ${wt.age})`);
+    }
+  }
+  if (unsafe.length > 0) {
+    console.log(`   \u26A0\uFE0F  ${unsafe.length} worktree(s) with unmerged changes kept:`);
+    for (const wt of unsafe) {
+      console.log(`      ${wt.name} (${wt.age})`);
+    }
+    console.log(`   Run "npx @groupchatai/claude-runner cleanup" to manage them.
+`);
+  }
+}
+async function interactiveCleanup(workDir) {
+  const worktrees = await listOurWorktrees(workDir);
+  if (worktrees.length === 0) {
+    console.log("\n\u{1F33F} No agent worktrees found.\n");
+    return;
+  }
+  console.log(`
+\u{1F33F} Found ${worktrees.length} worktree(s):
+`);
+  for (const wt of worktrees) {
+    const icon = wt.safeToRemove ? "\u2705" : "\u26A0\uFE0F ";
+    const status = wt.isMerged ? "Branch merged" : wt.hasUnpushed ? "Branch NOT merged, has unpushed commits" : "Branch NOT merged";
+    const safety = wt.safeToRemove ? "Safe to remove" : "Has unmerged work";
+    console.log(`  ${icon} ${wt.name}  (${wt.branch})`);
+    console.log(`     ${status} \u2022 Created ${wt.age} \u2022 ${safety}`);
+  }
+  const safe = worktrees.filter((w) => w.safeToRemove);
+  const unsafe = worktrees.filter((w) => !w.safeToRemove);
+  if (safe.length > 0) {
+    console.log(`
+Removing ${safe.length} safe worktree(s)\u2026`);
+    for (const wt of safe) {
+      const ok = await removeWorktree(workDir, wt);
+      if (ok) console.log(`   \u2705 Removed ${wt.name}`);
+    }
+  }
+  if (unsafe.length > 0) {
+    console.log(`
+\u26A0\uFE0F  ${unsafe.length} worktree(s) with unmerged work:`);
+    for (const wt of unsafe) {
+      console.log(`   Skipping ${wt.name} \u2014 has unmerged changes`);
+      console.log(`   To force remove: git worktree remove "${wt.path}" --force`);
+    }
+  }
+  console.log();
+}
+async function processRun(client, run, config, worktreeDir) {
   const runNum = ++runCounter;
   const runTag = `  ${C.pid}[${runNum}]${C.reset}`;
   const log = (msg) => console.log(`${runTag} ${msg}`);
@@ -480,11 +674,12 @@ async function processRun(client, run, config) {
     throw err;
   }
   log("\u25B6  Run started");
+  const effectiveCwd = worktreeDir ?? config.workDir;
   try {
-    if (runOptions.branch) {
+    if (!worktreeDir && runOptions.branch) {
       log(`\u{1F33F} Checking out branch: ${runOptions.branch}`);
       const git = spawn("git", ["checkout", runOptions.branch], {
-        cwd: config.workDir,
+        cwd: effectiveCwd,
         stdio: "pipe"
       });
       await new Promise((resolve) => git.on("close", () => resolve()));
@@ -504,14 +699,15 @@ async function processRun(client, run, config) {
       effectivePrompt,
       config,
       runOptions,
-      resumeSession
+      resumeSession,
+      effectiveCwd
     );
     log(`\u{1F916} Claude Code spawned (pid ${child.pid})${isFollowUp ? " (follow-up)" : ""}`);
     let { stdout, rawOutput, exitCode, sessionId, streamPrUrl } = await output;
     if (exitCode !== 0 && isFollowUp) {
       log(`\u26A0  Session resume failed, retrying with fresh session\u2026`);
       sessionCache.delete(run.taskId);
-      const retry = spawnClaudeCode(prompt, config, runOptions);
+      const retry = spawnClaudeCode(prompt, config, runOptions, void 0, effectiveCwd);
       log(`\u{1F916} Claude Code spawned (pid ${retry.process.pid}) (fresh)`);
       const retryResult = await retry.output;
       stdout = retryResult.stdout;
@@ -523,7 +719,7 @@ async function processRun(client, run, config) {
     if (sessionId) {
       sessionCache.set(run.taskId, sessionId);
     }
-    const pullRequestUrl = streamPrUrl ?? await detectPullRequestUrl(config.workDir) ?? extractPullRequestUrlFromOutput(stdout) ?? extractPullRequestUrlFromOutput(rawOutput);
+    const pullRequestUrl = streamPrUrl ?? await detectPullRequestUrl(effectiveCwd) ?? extractPullRequestUrlFromOutput(stdout) ?? extractPullRequestUrlFromOutput(rawOutput);
     if (exitCode !== 0) {
       const errorMsg = `Claude Code exited with code ${exitCode}:
 \`\`\`
@@ -576,6 +772,34 @@ function loadEnvFile() {
     }
   }
 }
+function showHelp() {
+  console.log(`
+Usage: npx @groupchatai/claude-runner [command] [options]
+
+Commands:
+  (default)    Start the agent runner
+  cleanup      Interactively review and remove stale worktrees
+
+Options:
+  --work-dir <path>     Repo directory for Claude Code to work in (default: cwd)
+  --poll                Use HTTP polling fallback (default: websocket, see below)
+  --poll-interval <ms>  Polling interval in milliseconds (default: 30000, only with --poll)
+  --max-concurrent <n>  Max concurrent tasks (default: 5)
+  --model <model>       Claude model to use (passed to claude CLI)
+  --dry-run             Poll and log runs without executing Claude Code
+  --once                Process one batch of pending runs and exit (implies --poll)
+  --verbose             Stream Claude Code activity with pid
+  --token <token>       Agent token (or set GCA_TOKEN env var)
+  --no-worktree         Disable git worktree isolation for runs
+  -h, --help            Show this help message
+
+Environment variables:
+  GCA_TOKEN             Agent token (gca_...)
+  GCA_API_URL           API URL override
+  GCA_CONVEX_URL        Convex URL override
+`);
+  process.exit(0);
+}
 function parseArgs() {
   loadEnvFile();
   const args = process.argv.slice(2);
@@ -584,12 +808,13 @@ function parseArgs() {
     apiUrl: process.env.GCA_API_URL ?? API_URL,
     convexUrl: process.env.GCA_CONVEX_URL ?? CONVEX_URL,
     workDir: process.cwd(),
-    pollInterval: 5e3,
-    maxConcurrent: 1,
+    pollInterval: 3e4,
+    maxConcurrent: 5,
     poll: false,
     dryRun: false,
     once: false,
-    verbose: false
+    verbose: false,
+    useWorktrees: true
   };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -598,7 +823,7 @@ function parseArgs() {
         config.workDir = path.resolve(args[++i] ?? ".");
         break;
       case "--poll-interval":
-        config.pollInterval = parseInt(args[++i] ?? "5000", 10);
+        config.pollInterval = parseInt(args[++i] ?? "30000", 10);
         break;
       case "--max-concurrent":
         config.maxConcurrent = parseInt(args[++i] ?? "1", 10);
@@ -621,6 +846,15 @@ function parseArgs() {
       case "--token":
         config.token = args[++i] ?? "";
         break;
+      case "--help":
+      case "-h":
+        showHelp();
+        break;
+      case "--no-worktree":
+        config.useWorktrees = false;
+        break;
+      case "cleanup":
+        break;
       default:
         console.error(`Unknown argument: ${arg}`);
         process.exit(1);
@@ -709,10 +943,21 @@ function handlePendingRuns(runs, scheduler, client, config) {
   }
 }
 async function processRunWithDrain(client, run, scheduler, config) {
+  let worktreeDir;
+  if (config.useWorktrees) {
+    try {
+      worktreeDir = createWorktree(config.workDir, run.taskId);
+      console.log(
+        `  \u{1F333} Worktree created from main \u2192 ${path.relative(config.workDir, worktreeDir)}`
+      );
+    } catch (err) {
+      console.error(`  \u26A0  Failed to create worktree, running in-place:`, err);
+    }
+  }
   let current = run;
   while (current) {
     try {
-      await processRun(client, current, config);
+      await processRun(client, current, config, worktreeDir);
     } catch (err) {
       console.error(`Unhandled error processing run ${current.id}:`, err);
     }
@@ -721,6 +966,15 @@ async function processRunWithDrain(client, run, scheduler, config) {
       console.log(`  \u23ED  Processing queued follow-up\u2026`);
     }
   }
+  if (worktreeDir) {
+    sessionCache.delete(run.taskId);
+    try {
+      removeWorktreeSimple(config.workDir, worktreeDir);
+      console.log(`  \u{1F9F9} Worktree cleaned up`);
+    } catch (err) {
+      console.error(`  \u26A0  Failed to clean up worktree:`, err);
+    }
+  }
 }
 async function runWithWebSocket(client, config, scheduler) {
   let ConvexClient;
@@ -730,6 +984,7 @@ async function runWithWebSocket(client, config, scheduler) {
     ({ anyApi } = await import("convex/server"));
   } catch {
     console.warn("\u26A0  convex package not found \u2014 falling back to HTTP polling.");
+    console.warn("   WebSocket mode is recommended for instant task pickup and zero idle cost.");
     console.warn("   Install convex for WebSocket mode: npm i convex\n");
     await runWithPolling(client, config, scheduler);
     return;
@@ -755,8 +1010,14 @@ async function runWithWebSocket(client, config, scheduler) {
   });
 }
 async function runWithPolling(client, config, scheduler) {
-  console.log(`\u{1F4E1} Polling every ${config.pollInterval}ms \u2014 listening for tasks\u2026
-`);
+  console.log(`\u{1F4E1} Polling every ${config.pollInterval / 1e3}s \u2014 listening for tasks\u2026`);
+  console.log(
+    `${C.dim}   Tip: WebSocket mode (default) picks up tasks instantly with zero idle cost.${C.reset}`
+  );
+  console.log(
+    `${C.dim}   Remove --poll unless your network blocks WebSocket connections.${C.reset}
+`
+  );
   let running = true;
   const shutdown = () => {
     console.log("\n\u{1F6D1} Shutting down\u2026");
@@ -788,6 +1049,14 @@ async function runWithPolling(client, config, scheduler) {
   }
 }
 async function main() {
+  if (process.argv.includes("cleanup")) {
+    loadEnvFile();
+    const workDir = process.cwd();
+    const workDirIdx = process.argv.indexOf("--work-dir");
+    const resolvedDir = workDirIdx >= 0 ? path.resolve(process.argv[workDirIdx + 1] ?? ".") : workDir;
+    await interactiveCleanup(resolvedDir);
+    return;
+  }
   const config = parseArgs();
   const client = new GroupChatAgentClient(config.apiUrl, config.token);
   let me;
@@ -805,7 +1074,11 @@ async function main() {
   if (config.apiUrl !== API_URL) console.log(`   API:   ${config.apiUrl}`);
   if (config.model) console.log(`   Model: ${config.model}`);
   if (config.dryRun) console.log(`   Mode:  DRY RUN`);
+  if (!config.useWorktrees) console.log(`   Worktrees: disabled`);
   console.log();
+  if (config.useWorktrees) {
+    await startupSweep(config.workDir);
+  }
   const scheduler = new TaskScheduler();
   if (config.poll || config.once) {
     await runWithPolling(client, config, scheduler);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groupchatai/claude-runner",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Run GroupChat AI agent tasks locally with Claude Code",
   "type": "module",
   "bin": {