@generativereality/agentherder 0.1.3 → 0.1.5

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.5",
+  "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.3";
+var version = "0.1.5";
 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",
@@ -618,20 +623,63 @@ const resumeCommand = define({
 function pathToProjectSlug(dir) {
 	return resolve(dir).replace(/\//g, "-");
 }
-/** Find the most recent Claude Code session ID for a directory */
-function findLatestSessionId(dir) {
-	const slug = pathToProjectSlug(dir);
-	const projectDir = join(homedir(), ".claude", "projects", slug);
+/** Find the most recent .jsonl session file in a Claude project directory */
+function latestJsonlIn(projectDir) {
 	if (!existsSync(projectDir)) return null;
-	const jsonlFiles = readdirSync(projectDir).filter((f) => extname(f) === ".jsonl").map((f) => ({
+	const files = readdirSync(projectDir).filter((f) => extname(f) === ".jsonl").map((f) => ({
 		name: f,
 		mtime: statSync(join(projectDir, f)).mtimeMs
 	})).sort((a, b) => b.mtime - a.mtime);
-	if (!jsonlFiles.length) return null;
-	return basename(jsonlFiles[0].name, ".jsonl");
+	return files.length ? basename(files[0].name, ".jsonl") : null;
+}
+/**
+* Find the most recent Claude Code session ID for a directory.
+* Also checks worktree subdirectories (.claude/worktrees/*) since tabs
+* opened with --worktree run from a worktree path, not the repo root.
+*/
+function findLatestSessionId(dir) {
+	const projectsRoot = join(homedir(), ".claude", "projects");
+	const direct = latestJsonlIn(join(projectsRoot, pathToProjectSlug(dir)));
+	if (direct) return direct;
+	const worktreesDir = join(dir, ".claude", "worktrees");
+	if (existsSync(worktreesDir)) {
+		const candidates = [];
+		for (const entry of readdirSync(worktreesDir)) {
+			const projectDir = join(projectsRoot, pathToProjectSlug(join(worktreesDir, entry)));
+			const id = latestJsonlIn(projectDir);
+			if (id) {
+				const mtime = statSync(join(projectDir, id + ".jsonl")).mtimeMs;
+				candidates.push({
+					id,
+					mtime
+				});
+			}
+		}
+		if (candidates.length) {
+			candidates.sort((a, b) => b.mtime - a.mtime);
+			return candidates[0].id;
+		}
+	}
+	return null;
 }
 //#endregion
 //#region src/commands/fork.ts
+/** If dir is inside .claude/worktrees/<name>, return the repo root instead */
+function resolveSessionDir(dir) {
+	const worktreeMarker = `${join(".claude", "worktrees")}/`;
+	const idx = dir.indexOf(worktreeMarker);
+	if (idx !== -1) {
+		const repoRoot = dir.slice(0, idx - 1);
+		return {
+			sessionLookupDir: repoRoot,
+			openDir: repoRoot
+		};
+	}
+	return {
+		sessionLookupDir: dir,
+		openDir: dir
+	};
+}
 const forkCommand = define({
 	name: "fork",
 	description: "Fork a session into a new tab (claude --resume <id> --fork-session)",
@@ -673,16 +721,16 @@ const forkCommand = define({
 			consola.error(`Tab "${tabName}" has no terminal block`);
 			process.exit(1);
 		}
-		const sourceDir = termBlocks[0].meta?.["cmd:cwd"] ?? process.cwd();
-		const sessionId = findLatestSessionId(sourceDir);
+		const { sessionLookupDir, openDir } = resolveSessionDir(termBlocks[0].meta?.["cmd:cwd"] ?? process.cwd());
+		const sessionId = findLatestSessionId(sessionLookupDir);
 		if (!sessionId) {
-			consola.error(`No Claude session found for ${sourceDir}`);
-			consola.info(`Looked in ~/.claude/projects/${pathToProjectSlug(sourceDir)}/`);
+			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: sourceDir,
+			dir: openDir,
 			claudeCmd: `claude --resume ${sessionId} --fork-session`
 		});
 		consola.success(`Forked "${tabName}" → "${newName}" [${newTabId.slice(0, 8)}]`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@generativereality/agentherder",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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,181 @@
+---
+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 try an alternative approach without disrupting the original:
+
+```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.
+
+## 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
+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