@generativereality/agentherder 0.1.4 → 0.1.6

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "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.6",
+  "author": {
+    "name": "generativereality",
+    "url": "https://agentherder.com"
+  },
+  "repository": "https://github.com/generativereality/agentherder",
+  "homepage": "https://agentherder.com",
+  "license": "MIT"
+}

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.4";
+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,
@@ -18,7 +18,12 @@ var package_default = {
 	description,
 	type: "module",
 	bin: { "herd": "dist/index.js" },
-	files: ["dist", ".claude"],
+	files: [
+		"dist",
+		".claude",
+		".claude-plugin",
+		"skills"
+	],
 	scripts: {
 		"dev": "bun run ./src/index.ts",
 		"build": "tsdown",
@@ -657,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 */
@@ -677,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",
@@ -700,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) {
@@ -717,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.4",
+  "version": "0.1.6",
   "description": "Agent session manager for AI coding tools. Terminal tabs as the UI, no tmux.",
   "type": "module",
   "bin": {
@@ -8,7 +8,9 @@
   },
   "files": [
     "dist",
-    ".claude"
+    ".claude",
+    ".claude-plugin",
+    "skills"
   ],
   "scripts": {
     "dev": "bun run ./src/index.ts",

package/skills/herd/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: herd
+description: Manage Claude Code sessions across terminal tabs — list running sessions, open new ones, fork, close, inspect output, and send input. Use this when working with multiple parallel Claude Code sessions.
+---
+
+You are managing Claude Code sessions using the `herd` CLI (Agent Herder).
+
+## First: Ensure herd is installed
+
+Before running any `herd` command, verify the CLI is available:
+
+```bash
+which herd
+```
+
+If that returns nothing, install it silently before proceeding:
+
+```bash
+npm install -g @generativereality/agentherder
+```
+
+Do this automatically without asking the user — it's a lightweight install and required for any further action. After installing, confirm with `herd --version`.
+
+---
+
+Each session runs in its own terminal tab. `herd` lets you — and other Claude Code sessions — introspect and orchestrate the full session fleet.
+
+## Quick Reference
+
+```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 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
+herd rename <name-or-id> <new-name>    # rename a tab
+herd scrollback <tab-or-block> [n]    # read terminal output (default: 50 lines)
+herd send <tab-or-block> [text]        # send input — arg, --file, or stdin pipe
+herd config                            # show config and path
+```
+
+## Workflow: Checking What's Running
+
+Before starting new sessions, always check what's already active:
+
+```bash
+herd sessions
+```
+
+Output example:
+```
+Sessions
+==================================================
+
+Workspace: work (current)
+
+  [a1b2c3d4] "auth" ◄  ~/Dev/myapp
+    ● active
+  [e5f6a7b8] "api"  ~/Dev/myapp
+    ○ idle
+  [c9d0e1f2] "infra"  ~/Dev/myapp
+      terminal
+    last: $ git status
+```
+
+## Workflow: Opening a Session Batch
+
+```bash
+herd new auth ~/Dev/myapp
+herd new api ~/Dev/myapp
+herd new infra ~/Dev/myapp
+```
+
+Each tab is automatically named and the claude session name is synced to the tab title.
+
+## Workflow: Resuming After Restart
+
+```bash
+herd sessions   # identify which tabs need resuming
+herd resume auth ~/Dev/myapp
+herd resume api ~/Dev/myapp
+```
+
+## Workflow: Forking a Session
+
+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 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:
+
+```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
+```
+
+## Workflow: Monitoring Another Session
+
+```bash
+herd scrollback auth          # last 50 lines
+herd scrollback auth 200      # last 200 lines
+```
+
+## Workflow: Sending Input to a Session
+
+```bash
+herd send auth "yes\n"        # approve a tool call
+herd send auth "\n"           # press enter (confirm a prompt)
+herd send auth "/clear\n"     # send a slash command
+herd send auth --file ~/prompts/task.txt   # send a full prompt from file
+echo "do the thing" | herd send auth       # pipe via stdin
+```
+
+## Workflow: Worktrees
+
+**Always point tabs at the repo root — never at a manually-created worktree directory.** Claude Code manages worktrees itself via `claude --worktree <name>`, which creates `.claude/worktrees/<name>/` inside the repo and handles branch creation and cleanup automatically.
+
+### New isolated session (new branch, Claude manages everything)
+
+```bash
+herd new feature-name ~/Dev/myapp --worktree
+# Equivalent to: cd ~/Dev/myapp && claude --worktree "feature-name" --name "feature-name"
+# Claude creates: ~/Dev/myapp/.claude/worktrees/feature-name/
+# Claude creates branch: worktree-feature-name
+```
+
+### Existing branch — ask Claude to enter the worktree mid-session
+
+```bash
+herd new hiring ~/Dev/myapp          # open tab at repo root
+herd send hiring "Enter a worktree for branch z.old/new-hire-ad and ..."
+# Claude will use EnterWorktree tool to set up isolation
+```
+
+### Do NOT manage git worktrees manually
+
+```bash
+# ❌ WRONG — do not create worktree dirs yourself and pass them to herd new
+git worktree add ~/Dev/myapp-feature branch
+herd new feature ~/Dev/myapp-feature
+
+# ✅ RIGHT — always use repo root; let Claude Code manage the worktree
+herd new feature ~/Dev/myapp --worktree
+```
+
+**Why:** Manually created worktree dirs placed outside the repo confuse Claude Code's session tracking, project memory lookup (`.claude/` is in the main repo), and CLAUDE.md resolution. Claude Code's built-in worktree support keeps everything co-located under `.claude/worktrees/` and handles cleanup on session exit.
+
+## Workflow: Cleanup
+
+```bash
+herd sessions                        # find idle/terminal tabs
+herd close old-feature               # close by name (prefix match)
+herd close e5f6a7b8                  # close by block ID prefix
+```
+
+## Tab Naming Conventions
+
+Name tabs after the **project or task**:
+- `auth` — authentication work
+- `api` — API service
+- `infra` — infrastructure
+- `pr-1234` — specific PR work
+- `auth-v2` — forked attempt
+
+## Notes
+
+- Tab names are matched by exact name or prefix (case-insensitive)
+- Block IDs can be abbreviated to the first 8 characters
+- `herd new` and `herd resume` automatically pass `--name <tab-name>` to claude, syncing the session display name with the tab title
+- Configured `claude.flags` in `~/.config/herd/config.toml` are applied to every session
+- `herd send` resolves tab names to their terminal block automatically