@generativereality/agentherder 0.1.5 → 0.1.7

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.7",
   "author": {
     "name": "generativereality",
     "url": "https://agentherder.com"

package/dist/index.js

@@ -4,13 +4,13 @@ import { cli, define } from "gunshi";
 import { createConnection } from "net";
 import { execFileSync, spawnSync } from "child_process";
 import { randomUUID } from "crypto";
-import { homedir } from "os";
+import { homedir, tmpdir } from "os";
 import { basename, dirname, extname, join, resolve } from "path";
 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.7";
 var description = "Agent session manager for AI coding tools. Terminal tabs as the UI, no tmux.";
 var package_default = {
 	name,
@@ -502,8 +502,21 @@ function ensureConfigExists() {
 }
 //#endregion
 //#region src/core/open-session.ts
+/** Poll scrollback until Claude's ❯ prompt is visible, then return */
+async function waitForClaudePrompt(adapter, blockId, timeoutMs = 3e4) {
+	const POLL_INTERVAL = 1e3;
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		await new Promise((r) => setTimeout(r, POLL_INTERVAL));
+		try {
+			const lines = adapter.scrollback(blockId, 10);
+			if (lines && lines.includes("❯")) return;
+		} catch {}
+	}
+	consola.warn("Timed out waiting for Claude prompt — sending task anyway");
+}
 async function openSession(opts) {
-	const { tabName, claudeCmd, workspaceQuery } = opts;
+	const { tabName, claudeCmd, workspaceQuery, initialPromptFile } = opts;
 	const dir = resolve(opts.dir.replace(/^~/, homedir()));
 	if (!existsSync(dir)) {
 		consola.error(`Directory does not exist: ${dir}`);
@@ -539,6 +552,12 @@ async function openSession(opts) {
 	const extraFlags = config.claude.flags.join(" ");
 	const cmd = `cd ${JSON.stringify(dir)} && ${claudeCmd} --name ${JSON.stringify(tabName)}${extraFlags ? " " + extraFlags : ""}\n`;
 	await adapter.sendInput(blockId, cmd);
+	if (initialPromptFile) {
+		await waitForClaudePrompt(adapter, blockId);
+		const prompt = readFileSync(initialPromptFile, "utf-8");
+		const text = prompt.endsWith("\n") ? prompt : prompt + "\n";
+		await adapter.sendInput(blockId, text);
+	}
 	await new Promise((r) => setTimeout(r, 2e3));
 	adapter.closeSocket();
 	return tabId;
@@ -566,6 +585,16 @@ const newCommand = define({
 			type: "boolean",
 			short: "W",
 			description: "Launch claude with --worktree <name> for isolated branch work"
+		},
+		file: {
+			type: "string",
+			short: "f",
+			description: "Send initial prompt from file once Claude is ready"
+		},
+		prompt: {
+			type: "string",
+			short: "p",
+			description: "Send initial prompt text once Claude is ready"
 		}
 	},
 	async run(ctx) {
@@ -573,15 +602,23 @@ const newCommand = define({
 		const dir = ctx.positionals[2] ?? process.cwd();
 		const workspace = ctx.values.workspace;
 		const useWorktree = ctx.values.worktree ?? false;
+		const promptFile = ctx.values.file;
+		const promptText = ctx.values.prompt;
 		if (!name) {
 			consola.error("Tab name is required");
 			process.exit(1);
 		}
+		let initialPromptFile;
+		if (promptText) {
+			initialPromptFile = join(tmpdir(), `herd-prompt-${Date.now()}.txt`);
+			writeFileSync(initialPromptFile, promptText);
+		} else if (promptFile) initialPromptFile = promptFile;
 		const tabId = await openSession({
 			tabName: name,
 			dir,
 			claudeCmd: useWorktree ? `claude --worktree ${JSON.stringify(name)}` : "claude",
-			workspaceQuery: workspace
+			workspaceQuery: workspace,
+			initialPromptFile
 		});
 		const suffix = useWorktree ? ` (worktree: .claude/worktrees/${name})` : "";
 		consola.success(`Tab "${name}" [${tabId.slice(0, 8)}] → claude at ${dir}${suffix}`);
@@ -662,6 +699,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 +744,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 +767,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 +784,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.7",
   "description": "Agent session manager for AI coding tools. Terminal tabs as the UI, no tmux.",
   "type": "module",
   "bin": {

package/skills/herd/SKILL.md

@@ -30,7 +30,7 @@ Each session runs in its own terminal tab. `herd` lets you — and other Claude
 ```bash
 herd sessions                          # list all tabs with session status
 herd list                              # list all workspaces, tabs, and blocks
-herd new <name> [dir] [-w workspace]   # new tab + claude
+herd new <name> [dir] [-w workspace] [-p "prompt"] [-f file]  # new tab + claude
 herd resume <name> [dir]               # new tab + claude --continue
 herd fork <tab-name> [-n new-name]     # fork a session into a new tab
 herd close <name-or-id>                # close a tab
@@ -84,26 +84,44 @@ 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
 
 As a Claude Code session, you can spawn a sibling session to work on a parallel task:
 
+**Preferred: pass the initial task directly to `herd new`** using `--prompt` or `--file`. This polls internally until Claude's `❯` prompt appears before sending — no race condition:
+
+```bash
+herd new payments ~/Dev/myapp --prompt "implement the billing endpoint"
+herd new payments ~/Dev/myapp --file /tmp/task.txt
+```
+
+If you need to send a task after the fact, poll first:
+
 ```bash
 herd new payments ~/Dev/myapp
-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
+# Poll until ❯ appears (typically 10-15s with MCP servers)
+herd scrollback payments 5   # repeat until you see ❯
+herd send payments --file /tmp/task.txt
+herd send payments "yes\n"   # quick replies
 ```
 
+**Do NOT call `herd send` immediately after `herd new`** — Claude is still starting up and the text will land as raw shell commands.
+
 ## Workflow: Monitoring Another Session
 
 ```bash