@generativereality/agentherder 0.1.5 → 0.1.6

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agentherder",
   "description": "Run a fleet of Claude Code sessions. Terminal tabs as the UI, no tmux. Claude can orchestrate its own sibling sessions.",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "author": {
     "name": "generativereality",
     "url": "https://agentherder.com"

package/dist/index.js

@@ -10,7 +10,7 @@ import { consola } from "consola";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
 //#region package.json
 var name = "@generativereality/agentherder";
-var version = "0.1.5";
+var version = "0.1.6";
 var description = "Agent session manager for AI coding tools. Terminal tabs as the UI, no tmux.";
 var package_default = {
 	name,
@@ -662,6 +662,31 @@ function findLatestSessionId(dir) {
 	}
 	return null;
 }
+/**
+* Find the most recently created session ID after a given timestamp.
+* Used by `herd fork` to detect the session Claude created in response to /branch.
+*/
+function findNewestSessionIdSince(dir, sinceMs) {
+	const projectsRoot = join(homedir(), ".claude", "projects");
+	const candidates = [];
+	function scanProjectDir(projectDir) {
+		if (!existsSync(projectDir)) return;
+		for (const f of readdirSync(projectDir)) {
+			if (extname(f) !== ".jsonl") continue;
+			const mtime = statSync(join(projectDir, f)).mtimeMs;
+			if (mtime > sinceMs) candidates.push({
+				id: basename(f, ".jsonl"),
+				mtime
+			});
+		}
+	}
+	scanProjectDir(join(projectsRoot, pathToProjectSlug(dir)));
+	const worktreesDir = join(dir, ".claude", "worktrees");
+	if (existsSync(worktreesDir)) for (const entry of readdirSync(worktreesDir)) scanProjectDir(join(projectsRoot, pathToProjectSlug(join(worktreesDir, entry))));
+	if (!candidates.length) return null;
+	candidates.sort((a, b) => b.mtime - a.mtime);
+	return candidates[0].id;
+}
 //#endregion
 //#region src/commands/fork.ts
 /** If dir is inside .claude/worktrees/<name>, return the repo root instead */
@@ -682,7 +707,7 @@ function resolveSessionDir(dir) {
 }
 const forkCommand = define({
 	name: "fork",
-	description: "Fork a session into a new tab (claude --resume <id> --fork-session)",
+	description: "Fork a session into a new tab by sending /branch to the source tab",
 	args: {
 		tab: {
 			type: "positional",
@@ -705,7 +730,7 @@ const forkCommand = define({
 		const { tabsById, tabNames } = await adapter.getAllData();
 		const matches = adapter.resolveTab(sourceQuery, tabsById, tabNames);
 		if (!matches.length) {
-			consola.error(`No tab matching '${sourceQuery}'`);
+			consola.error(`No tab matching '${sourceQuery}' (tabs in workspaces with no open window are not visible — open that workspace first)`);
 			process.exit(1);
 		}
 		if (matches.length > 1) {
@@ -722,19 +747,43 @@ const forkCommand = define({
 			process.exit(1);
 		}
 		const { sessionLookupDir, openDir } = resolveSessionDir(termBlocks[0].meta?.["cmd:cwd"] ?? process.cwd());
-		const sessionId = findLatestSessionId(sessionLookupDir);
-		if (!sessionId) {
-			consola.error(`No Claude session found for ${sessionLookupDir}`);
-			consola.info(`Looked in ~/.claude/projects/${pathToProjectSlug(sessionLookupDir)}/`);
-			process.exit(1);
+		const sourceBlockId = termBlocks[0].blockid;
+		consola.info(`Sending /branch to "${tabName}"…`);
+		const before = Date.now();
+		await adapter.sendInput(sourceBlockId, "/branch\n");
+		adapter.closeSocket();
+		const POLL_INTERVAL = 500;
+		const TIMEOUT = 1e4;
+		let newSessionId = null;
+		const deadline = Date.now() + TIMEOUT;
+		while (Date.now() < deadline) {
+			await new Promise((r) => setTimeout(r, POLL_INTERVAL));
+			newSessionId = findNewestSessionIdSince(sessionLookupDir, before);
+			if (newSessionId) break;
+		}
+		if (!newSessionId) {
+			consola.warn("No new session detected after /branch — falling back to --fork-session");
+			const fallbackId = findLatestSessionId(sessionLookupDir);
+			if (!fallbackId) {
+				consola.error(`No Claude session found for ${sessionLookupDir}`);
+				consola.info(`Looked in ~/.claude/projects/${pathToProjectSlug(sessionLookupDir)}/`);
+				process.exit(1);
+			}
+			const newTabId = await openSession({
+				tabName: newName,
+				dir: openDir,
+				claudeCmd: `claude --resume ${fallbackId} --fork-session`
+			});
+			consola.success(`Forked "${tabName}" → "${newName}" [${newTabId.slice(0, 8)}] (via --fork-session)`);
+			return;
 		}
 		const newTabId = await openSession({
 			tabName: newName,
 			dir: openDir,
-			claudeCmd: `claude --resume ${sessionId} --fork-session`
+			claudeCmd: `claude --resume ${newSessionId}`
 		});
 		consola.success(`Forked "${tabName}" → "${newName}" [${newTabId.slice(0, 8)}]`);
-		consola.info(`session: ${sessionId}`);
+		consola.info(`session: ${newSessionId}`);
 	}
 });
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@generativereality/agentherder",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Agent session manager for AI coding tools. Terminal tabs as the UI, no tmux.",
   "type": "module",
   "bin": {

package/skills/herd/SKILL.md

@@ -84,14 +84,20 @@ herd resume api ~/Dev/myapp
 
 ## Workflow: Forking a Session
 
-Use `fork` when you want to try an alternative approach without disrupting the original:
+Use `fork` when you want to explore an alternative approach without disrupting the original.
+`herd fork` sends `/branch` to the source tab (Claude's built-in conversation fork command),
+waits for the new session to be written, then opens it in a new tab.
 
 ```bash
 herd fork auth                    # creates "auth-fork" tab
 herd fork auth -n "auth-v2"       # creates "auth-v2" tab
 ```
 
-The forked session runs `claude --resume <session-id> --fork-session` — it shares context from the original but creates an independent new session.
+The forked session shares full conversation history up to the branch point, then diverges independently.
+If Claude does not respond to `/branch` in time, herd falls back to `claude --resume <id> --fork-session`.
+
+**In-session equivalent**: typing `/branch` (alias `/fork`) directly in Claude produces the same fork —
+use `herd resume <name> <dir>` afterwards to open the resulting session in a new tab.
 
 ## Workflow: Spawning a Parallel Agent
 
@@ -99,6 +105,21 @@ As a Claude Code session, you can spawn a sibling session to work on a parallel
 
 ```bash
 herd new payments ~/Dev/myapp
+```
+
+**CRITICAL: Wait for Claude to be ready before sending tasks.** After `herd new` returns, Claude is still starting up (loading MCP servers, showing the initial prompt). Sending immediately causes the task to arrive as raw shell commands, not as a Claude prompt.
+
+Poll `herd scrollback` until you see the Claude prompt (the `❯` line with no pending output):
+
+```bash
+# Poll until Claude prompt appears (look for the ❯ prompt line)
+herd scrollback payments 5
+# Repeat every few seconds until you see Claude's prompt — typically 10-15s
+```
+
+Once Claude is ready, send the task:
+
+```bash
 herd send payments --file /tmp/task.txt     # send a prompt from a file
 echo "implement the billing endpoint" | herd send payments   # or via stdin
 herd send payments "yes\n"                  # or inline for quick replies