@generativereality/herd 0.1.0

package/.claude/skills/herd/SKILL.md

@@ -0,0 +1,147 @@
+---
+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/herd
+```
+
+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: 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

package/README.md

@@ -0,0 +1,180 @@
+# Agent Herder
+
+**Run a fleet of Claude Code sessions. From the CLI — or from Claude itself.**
+
+CLI command: `herd` · Website: [agentherder.com](https://agentherder.com)
+
+```bash
+herd new auth ~/Dev/myapp       # new tab, claude starts
+herd new api ~/Dev/myapp
+herd new infra ~/Dev/myapp
+
+herd sessions                   # what's running across all tabs
+herd scrollback auth            # read what auth is doing without switching tabs
+herd send api --file task.txt   # drop a prompt into any session
+herd fork auth -n auth-v2       # branch a conversation, keep the original
+```
+
+No tmux. No dashboard. Your terminal tabs are the UI.
+
+---
+
+## The idea
+
+When you're running multiple Claude Code sessions in parallel, you lose track fast. Which tab is working on what? Did it finish? Is it waiting for input?
+
+herd solves this with a simple CLI that treats **terminal tabs as the unit of orchestration** — open them by name, read their output, send them prompts, fork them, close them. Everything stays in sync: the tab title, the Claude session name, and the working directory.
+
+The killer feature: **Claude can run herd itself.** Install the skill and your Claude Code session can spawn parallel sibling sessions, monitor their output, and coordinate across them — without you switching tabs.
+
+## Install
+
+**As a Claude Code plugin** (installs the CLI + skill in one step):
+
+```bash
+/plugin marketplace add generativereality/plugins
+/plugin install agentherder@generativereality
+```
+
+**Via npm** (CLI only):
+
+```bash
+npm install -g @generativereality/herd
+```
+
+**Skill only** (if you already have the CLI):
+
+```bash
+mkdir -p .claude/skills/herd
+curl -fsSL https://raw.githubusercontent.com/generativereality/agentherder/main/skills/herd/SKILL.md \
+  -o .claude/skills/herd/SKILL.md
+```
+
+**Requirements:** [Wave Terminal](https://waveterm.dev) · macOS · Node.js 20+
+
+**One-time:** Wave needs Accessibility permission — System Settings → Privacy & Security → Accessibility → Wave ✓
+
+## Usage
+
+```
+herd sessions                          what's running (active/idle status)
+herd list                              all workspaces, tabs, and blocks
+herd new <name> [dir] [-w workspace]   open tab, start claude
+herd resume <name> [dir]               open tab, run claude --continue
+herd fork <tab> [-n new-name]          fork a session into a new tab
+herd close <tab>                       close a tab
+herd rename <tab> <new-name>           rename a tab
+herd scrollback <tab> [lines]          read terminal output (default: 50 lines)
+herd send <tab> [text]                 send input — arg, --file, or stdin pipe
+herd config                            show config path and values
+```
+
+Tab names match by prefix. Block IDs can be shortened to 8 chars.
+
+### Spin up a session fleet
+
+```bash
+herd sessions                 # check what's already running first
+
+herd new auth ~/Dev/myapp
+herd new payments ~/Dev/myapp
+herd new infra ~/Dev/myapp
+```
+
+Each tab gets named, Claude's session name syncs to the tab title via `--name`.
+
+### Send a prompt
+
+```bash
+# From a file (good for long context-heavy prompts)
+herd send auth --file ~/prompts/task.txt
+
+# Via stdin
+echo "focus on the edge cases in the OAuth flow" | herd send auth
+
+# Quick reply or approval
+herd send auth "yes\n"
+herd send auth "/clear\n"
+```
+
+### Check in without switching tabs
+
+```bash
+herd scrollback auth          # last 50 lines
+herd scrollback auth 200      # last 200 lines
+```
+
+### Fork a session
+
+```bash
+# Try a different approach without losing the original conversation
+herd fork auth -n auth-v2
+```
+
+Runs `claude --resume <id> --fork-session` — new independent session, full shared context from the original.
+
+### Target a workspace
+
+```bash
+herd new api ~/Dev/myapp -w work
+```
+
+## Claude Code Skill
+
+The real unlock: install the plugin (see [Install](#install)) so **Claude Code can herd itself**.
+
+With the skill installed, Claude can:
+
+- Check what's running before starting duplicate work (`herd sessions`)
+- Spawn a parallel session for an independent subtask (`herd new payments ~/Dev/myapp`)
+- Monitor siblings without interrupting them (`herd scrollback payments`)
+- Drop a prompt into any session (`herd send payments --file spec.txt`)
+- Fork its own session to explore an alternative approach (`herd fork auth`)
+
+Claude becomes the orchestrator of its own fleet.
+
+## Tip: pair with Claude Code Remote Control
+
+Claude Code's [Remote Control](https://docs.anthropic.com/en/docs/claude-code/remote-control) lets you access a local session from any device — phone, tablet, browser — via `claude.ai/code`. The session still runs on your machine, with full filesystem and tool access.
+
+Paired with Agent Herder, the pattern is:
+
+1. Start a **command session** with Remote Control enabled:
+   ```bash
+   claude --remote-control "command"
+   ```
+2. From your phone or browser, connect to that session and assign work:
+   > *"Spawn three sessions — auth, payments, infra — and start them on these tasks..."*
+3. The command session uses `herd` to open tabs, send prompts, and check in on workers
+4. You monitor and steer the whole fleet from your phone while the machine does the work
+
+One remote-controlled session orchestrating a local fleet.
+
+## Config
+
+```toml
+# ~/.config/herd/config.toml
+
+[claude]
+# Flags passed to every claude invocation
+flags = ["--allow-dangerously-skip-permissions"]
+
+[defaults]
+# Default Wave workspace for new sessions
+# workspace = ""
+```
+
+## Terminal support
+
+| Terminal | Status |
+|----------|--------|
+| [Wave Terminal](https://waveterm.dev) | ✅ Full support |
+| iTerm2 | Planned |
+| Ghostty | Planned |
+| Warp | Planned |
+
+Wave is supported via its unix socket RPC. Other terminals will follow as adapters — PRs welcome.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,927 @@
+#!/usr/bin/env node
+import updateNotifier from "update-notifier";
+import { cli, define } from "gunshi";
+import { createConnection } from "net";
+import { execFileSync, spawnSync } from "child_process";
+import { randomUUID } from "crypto";
+import { homedir } 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/herd";
+var version = "0.1.0";
+var description = "Agent session manager for AI coding tools. Terminal tabs as the UI, no tmux.";
+var package_default = {
+	name,
+	version,
+	description,
+	type: "module",
+	bin: { "herd": "dist/index.js" },
+	files: ["dist", ".claude"],
+	scripts: {
+		"dev": "bun run ./src/index.ts",
+		"build": "tsdown",
+		"typecheck": "tsc --noEmit",
+		"lint": "eslint src/",
+		"check": "bun run typecheck && bun run build",
+		"release": "bumpp && npm publish",
+		"prepack": "bun run build"
+	},
+	keywords: [
+		"claude-code",
+		"ai-agents",
+		"session-manager",
+		"wave-terminal",
+		"herd",
+		"agentherder"
+	],
+	author: "motin",
+	license: "MIT",
+	repository: {
+		"type": "git",
+		"url": "https://github.com/generativereality/agentherder"
+	},
+	homepage: "https://agentherder.com",
+	engines: { "node": ">=20.19.4" },
+	publishConfig: {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	},
+	dependencies: {
+		"@clack/prompts": "^0.9.1",
+		"consola": "^3.4.0",
+		"gunshi": "^0.23.0",
+		"update-notifier": "^7.3.1"
+	},
+	devDependencies: {
+		"@types/node": "^22.0.0",
+		"@types/update-notifier": "^6.0.8",
+		"bumpp": "^9.11.1",
+		"tsdown": "^0.12.0",
+		"typescript": "^5.8.0"
+	}
+};
+//#endregion
+//#region src/core/terminal.ts
+function detectTerminal() {
+	if (process.env.WAVETERM_JWT) return "wave";
+	const prog = process.env.TERM_PROGRAM ?? "";
+	const term = process.env.TERM ?? "";
+	if (prog === "iTerm.app") return "iterm2";
+	if (prog === "ghostty" || process.env.GHOSTTY_RESOURCES_DIR) return "ghostty";
+	if (prog === "WarpTerminal") return "warp";
+	if (prog === "vscode") return "vscode";
+	if (prog === "Hyper") return "hyper";
+	if (prog === "Apple_Terminal") return "apple-terminal";
+	if (term === "xterm-kitty" || process.env.KITTY_WINDOW_ID) return "kitty";
+	if (term === "alacritty") return "alacritty";
+	return "unknown";
+}
+const TERMINAL_NAMES = {
+	wave: "Wave Terminal",
+	iterm2: "iTerm2",
+	ghostty: "Ghostty",
+	warp: "Warp",
+	kitty: "Kitty",
+	vscode: "VS Code terminal",
+	hyper: "Hyper",
+	alacritty: "Alacritty",
+	"apple-terminal": "Terminal.app",
+	unknown: "an unrecognised terminal"
+};
+function printUnsupportedTerminalError(terminal) {
+	const name = TERMINAL_NAMES[terminal];
+	const lines = [
+		"",
+		`  Agent Herder currently requires Wave Terminal.`,
+		`  You appear to be running in: ${name}`,
+		"",
+		`  Option 1 — Switch to Wave Terminal (full support today):`,
+		`    brew install --cask wave`,
+		`    https://waveterm.dev`,
+		"",
+		`  Option 2 — Add ${name} support (one adapter file, PRs welcome):`,
+		`    git clone https://github.com/generativereality/agentherder`,
+		`    cd agentherder`,
+		`    claude   # ask Claude to implement the ${name} adapter`,
+		"",
+		`    Claude will find src/core/wave.ts, use it as the reference`,
+		`    implementation, create src/core/${adapterFileName(terminal)},`,
+		`    wire it up, and open a PR — all in one session.`,
+		""
+	];
+	console.error(lines.join("\n"));
+}
+function adapterFileName(terminal) {
+	if (terminal === "unknown") return "<terminal>.ts";
+	return `${terminal}.ts`;
+}
+//#endregion
+//#region src/core/wave.ts
+const SOCK_PATH = join(homedir(), "Library", "Application Support", "waveterm", "wave.sock");
+var WaveSocket = class {
+	socket;
+	buffer = "";
+	pendingReaders = [];
+	routeId = "";
+	jwt;
+	constructor(jwt) {
+		this.jwt = jwt;
+		this.socket = createConnection(SOCK_PATH);
+		this.socket.on("data", (chunk) => {
+			this.buffer += chunk.toString();
+			let nl;
+			while ((nl = this.buffer.indexOf("\n")) !== -1) {
+				const line = this.buffer.slice(0, nl).trim();
+				this.buffer = this.buffer.slice(nl + 1);
+				if (!line) continue;
+				try {
+					const msg = JSON.parse(line);
+					this.pendingReaders.shift()?.(msg);
+				} catch {}
+			}
+		});
+	}
+	waitForMessage(timeoutMs = 8e3) {
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				const idx = this.pendingReaders.indexOf(resolve);
+				if (idx !== -1) this.pendingReaders.splice(idx, 1);
+				reject(/* @__PURE__ */ new Error("Wave socket timeout"));
+			}, timeoutMs);
+			this.pendingReaders.push((msg) => {
+				clearTimeout(timer);
+				resolve(msg);
+			});
+		});
+	}
+	send(msg) {
+		this.socket.write(JSON.stringify(msg) + "\n");
+	}
+	async connect() {
+		await new Promise((resolve, reject) => {
+			this.socket.once("connect", resolve);
+			this.socket.once("error", reject);
+		});
+		this.send({
+			command: "authenticate",
+			reqid: randomUUID(),
+			route: "$control",
+			data: this.jwt
+		});
+		this.routeId = (await this.waitForMessage()).data.routeid;
+	}
+	async command(command, data, route = "wavesrv") {
+		this.send({
+			command,
+			reqid: randomUUID(),
+			route,
+			source: this.routeId,
+			data
+		});
+		try {
+			return await this.waitForMessage();
+		} catch {
+			return null;
+		}
+	}
+	destroy() {
+		this.socket.destroy();
+	}
+};
+var WaveAdapter = class {
+	socket = null;
+	jwt;
+	constructor() {
+		this.jwt = process.env.WAVETERM_JWT ?? "";
+	}
+	blocksList() {
+		try {
+			const out = execFileSync("wsh", [
+				"blocks",
+				"list",
+				"--json"
+			], { encoding: "utf-8" });
+			return JSON.parse(out);
+		} catch {
+			return [];
+		}
+	}
+	scrollback(blockId, lastN = 50) {
+		return spawnSync("wsh", [
+			"termscrollback",
+			"-b",
+			blockId,
+			"--start",
+			`-${lastN}`
+		], { encoding: "utf-8" }).stdout ?? "";
+	}
+	deleteBlock(blockId) {
+		spawnSync("wsh", [
+			"deleteblock",
+			"-b",
+			blockId
+		], { encoding: "utf-8" });
+	}
+	async newTab(focusWindowId) {
+		if (focusWindowId) {
+			await this.focusWindow(focusWindowId);
+			await sleep(300);
+		}
+		const r = spawnSync("osascript", ["-e", [
+			"tell application \"Wave\" to activate",
+			"delay 0.25",
+			"tell application \"System Events\" to keystroke \"t\" using command down"
+		].join("\n")], { encoding: "utf-8" });
+		if (r.status !== 0) {
+			const msg = r.stderr?.trim();
+			throw new Error(msg ? `osascript failed: ${msg}` : "Failed to open new tab — ensure Wave Terminal has Accessibility permission:\n  System Settings → Privacy & Security → Accessibility → Wave ✓");
+		}
+		return true;
+	}
+	async waitForNewBlock(beforeIds, timeoutMs = 5e3) {
+		const deadline = Date.now() + timeoutMs;
+		while (Date.now() < deadline) {
+			await sleep(250);
+			for (const b of this.blocksList()) if (b.view === "term" && !beforeIds.has(b.blockid)) return {
+				blockId: b.blockid,
+				tabId: b.tabid
+			};
+		}
+		return null;
+	}
+	async sock() {
+		if (!this.socket) {
+			const s = new WaveSocket(this.jwt);
+			await s.connect();
+			this.socket = s;
+		}
+		return this.socket;
+	}
+	closeSocket() {
+		this.socket?.destroy();
+		this.socket = null;
+	}
+	async getTab(tabId) {
+		return (await (await this.sock()).command("gettab", tabId))?.data ?? {};
+	}
+	async workspaceList() {
+		return (await (await this.sock()).command("workspacelist", null))?.data ?? [];
+	}
+	async focusWindow(windowId) {
+		await (await this.sock()).command("focuswindow", windowId, "electron");
+	}
+	async renameTab(tabId, name) {
+		await (await this.sock()).command("updatetabname", { args: [tabId, name] });
+	}
+	async sendInput(blockId, text) {
+		const s = await this.sock();
+		const inputdata64 = Buffer.from(text).toString("base64");
+		return s.command("controllerinput", {
+			blockid: blockId,
+			inputdata64
+		});
+	}
+	async getAllData() {
+		const blocks = this.blocksList();
+		const tabsById = /* @__PURE__ */ new Map();
+		for (const b of blocks) {
+			const arr = tabsById.get(b.tabid) ?? [];
+			arr.push(b);
+			tabsById.set(b.tabid, arr);
+		}
+		const tabNames = /* @__PURE__ */ new Map();
+		let workspaces = [];
+		try {
+			for (const tabId of tabsById.keys()) {
+				const td = await this.getTab(tabId);
+				tabNames.set(tabId, td.name ?? tabId.slice(0, 8));
+			}
+			workspaces = await this.workspaceList();
+		} catch {} finally {
+			this.closeSocket();
+		}
+		if (!workspaces.length) {
+			const wsId = process.env.WAVETERM_WORKSPACEID ?? "";
+			workspaces = [{
+				workspacedata: {
+					oid: wsId,
+					name: wsId.slice(0, 8) || "default",
+					tabids: [...tabsById.keys()]
+				},
+				windowid: ""
+			}];
+		}
+		return {
+			blocks,
+			tabsById,
+			workspaces,
+			tabNames
+		};
+	}
+	resolveTab(query, tabsById, tabNames) {
+		const q = query.toLowerCase();
+		return [...tabsById.keys()].filter((tid) => {
+			const name = tabNames.get(tid) ?? "";
+			return name.toLowerCase() === q || tid.startsWith(query) || name.toLowerCase().startsWith(q);
+		});
+	}
+	resolveBlock(query, blocks) {
+		return blocks.filter((b) => b.blockid.startsWith(query));
+	}
+	resolveWorkspace(workspaces, query) {
+		const q = query.toLowerCase();
+		return workspaces.filter(({ workspacedata: wd }) => {
+			const name = wd.name ?? "";
+			return name.toLowerCase() === q || wd.oid.startsWith(query) || name.toLowerCase().startsWith(q);
+		}).map((w) => ({
+			data: w.workspacedata,
+			windowId: w.windowid
+		}));
+	}
+};
+function requireWaveAdapter() {
+	if (!process.env.WAVETERM_JWT) {
+		printUnsupportedTerminalError(detectTerminal());
+		process.exit(1);
+	}
+	return new WaveAdapter();
+}
+function sleep(ms) {
+	return new Promise((r) => setTimeout(r, ms));
+}
+//#endregion
+//#region src/commands/sessions.ts
+const sessionsCommand = define({
+	name: "sessions",
+	description: "List tabs with active/idle session status",
+	args: {},
+	async run() {
+		const adapter = requireWaveAdapter();
+		const { tabsById, workspaces, tabNames } = await adapter.getAllData();
+		const currentTab = process.env.WAVETERM_TABID ?? "";
+		const currentWs = process.env.WAVETERM_WORKSPACEID ?? "";
+		console.log("Sessions");
+		console.log("=".repeat(50));
+		for (const wsp of workspaces) {
+			const { oid, name, tabids } = wsp.workspacedata;
+			const wsMarker = oid === currentWs ? " (current)" : "";
+			const tabIds = tabids.filter((t) => tabsById.has(t));
+			if (!tabIds.length) continue;
+			console.log(`\nWorkspace: ${name}${wsMarker}`);
+			for (const tabId of tabIds) {
+				const termBlocks = (tabsById.get(tabId) ?? []).filter((b) => b.view === "term");
+				if (!termBlocks.length) continue;
+				const name = tabNames.get(tabId) ?? tabId.slice(0, 8);
+				const cur = tabId === currentTab ? " ◄" : "";
+				const b = termBlocks[0];
+				const cwd = (b.meta?.["cmd:cwd"] ?? "").replace(process.env.HOME ?? "", "~");
+				const tail = adapter.scrollback(b.blockid, 5);
+				const lastLine = tail.split("\n").map((l) => l.trim()).filter(Boolean).at(-1) ?? "";
+				let status = "terminal";
+				if ([
+					"Claude Code",
+					"claude.ai/code",
+					"✻ Thinking",
+					"✽ Hatching",
+					"⏵⏵ bypass"
+				].some((s) => tail.includes(s))) status = "active";
+				else if (lastLine.toLowerCase().includes("claude")) status = "idle";
+				const statusLabel = status === "active" ? "● active" : status === "idle" ? "○ idle" : "  terminal";
+				console.log(`  [${tabId.slice(0, 8)}] "${name}"${cur}  ${cwd}`);
+				console.log(`    ${statusLabel}`);
+				if (status === "terminal" && lastLine) console.log(`    last: ${lastLine.slice(0, 80)}`);
+			}
+		}
+	}
+});
+//#endregion
+//#region src/commands/list.ts
+const listCommand = define({
+	name: "list",
+	description: "List all workspaces, tabs, and blocks",
+	args: {},
+	async run() {
+		const { tabsById, workspaces, tabNames } = await requireWaveAdapter().getAllData();
+		const currentBlock = process.env.WAVETERM_BLOCKID ?? "";
+		const currentTab = process.env.WAVETERM_TABID ?? "";
+		const currentWs = process.env.WAVETERM_WORKSPACEID ?? "";
+		for (const wsp of workspaces) {
+			const { oid, name, tabids } = wsp.workspacedata;
+			const noWindow = !wsp.windowid ? "  (no window)" : "";
+			const wsMarker = oid === currentWs ? "  ◄ current" : noWindow;
+			console.log(`Workspace: ${name}  [${oid.slice(0, 8)}]${wsMarker}`);
+			console.log();
+			const tabIds = tabids.filter((t) => tabsById.has(t));
+			if (!tabIds.length) {
+				console.log("  (no open tabs)");
+				console.log();
+				continue;
+			}
+			for (const tabId of tabIds) {
+				const tabName = tabNames.get(tabId) ?? tabId.slice(0, 8);
+				const cur = tabId === currentTab ? "  ◄" : "";
+				console.log(`  Tab  "${tabName}"  [${tabId.slice(0, 8)}]${cur}`);
+				for (const b of tabsById.get(tabId) ?? []) {
+					const here = b.blockid === currentBlock ? "  ◄ here" : "";
+					const cwd = b.meta?.["cmd:cwd"] ?? "";
+					console.log(`    ${b.view.padEnd(8)}  ${b.blockid.slice(0, 8)}${cwd ? `  ${cwd}` : ""}${here}`);
+				}
+				console.log();
+			}
+		}
+	}
+});
+//#endregion
+//#region src/core/config.ts
+const CONFIG_PATH = join(homedir(), ".config", "herd", "config.toml");
+const DEFAULT_CONFIG = {
+	claude: { flags: ["--allow-dangerously-skip-permissions"] },
+	defaults: { workspace: "" }
+};
+const DEFAULT_CONFIG_FILE = `# herd configuration
+# https://agentherder.com
+
+[claude]
+# Extra flags passed to every \`claude\` invocation.
+flags = ["--allow-dangerously-skip-permissions"]
+
+[defaults]
+# Default Wave workspace to open new sessions in.
+# workspace = ""
+`;
+function parseToml(text) {
+	const result = {};
+	let section = null;
+	for (const raw of text.split("\n")) {
+		const line = raw.trim();
+		if (!line || line.startsWith("#")) continue;
+		if (line.startsWith("[") && line.endsWith("]")) {
+			section = line.slice(1, -1).trim();
+			result[section] ??= {};
+			continue;
+		}
+		if (section && line.includes("=")) {
+			const [rawKey, ...rest] = line.split("=");
+			const key = rawKey.trim();
+			const val = rest.join("=").trim();
+			if (val.startsWith("[")) {
+				const items = [...val.matchAll(/"([^"]*)"/g)].map((m) => m[1]);
+				result[section][key] = items;
+			} else if (val.startsWith("\"") && val.endsWith("\"")) result[section][key] = val.slice(1, -1);
+			else if (val === "true" || val === "false") result[section][key] = val === "true";
+		}
+	}
+	return result;
+}
+function loadConfig() {
+	const config = {
+		claude: { ...DEFAULT_CONFIG.claude },
+		defaults: { ...DEFAULT_CONFIG.defaults }
+	};
+	if (!existsSync(CONFIG_PATH)) return config;
+	try {
+		const parsed = parseToml(readFileSync(CONFIG_PATH, "utf-8"));
+		if (parsed.claude) Object.assign(config.claude, parsed.claude);
+		if (parsed.defaults) Object.assign(config.defaults, parsed.defaults);
+	} catch {}
+	return config;
+}
+function ensureConfigExists() {
+	if (!existsSync(CONFIG_PATH)) {
+		mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+		writeFileSync(CONFIG_PATH, DEFAULT_CONFIG_FILE);
+	}
+	return CONFIG_PATH;
+}
+//#endregion
+//#region src/core/open-session.ts
+async function openSession(opts) {
+	const { tabName, claudeCmd, workspaceQuery } = opts;
+	const dir = resolve(opts.dir.replace(/^~/, homedir()));
+	const config = loadConfig();
+	const adapter = requireWaveAdapter();
+	let focusWindowId;
+	if (workspaceQuery) {
+		const { workspaces } = await adapter.getAllData();
+		const matches = adapter.resolveWorkspace(workspaces, workspaceQuery);
+		if (!matches.length) {
+			consola.error(`No workspace matching '${workspaceQuery}'`);
+			process.exit(1);
+		}
+		const { data, windowId } = matches[0];
+		if (!windowId) {
+			consola.error(`Workspace '${data.name}' has no open window`);
+			process.exit(1);
+		}
+		focusWindowId = windowId;
+		consola.info(`Workspace: ${data.name}`);
+	}
+	const beforeIds = new Set(adapter.blocksList().filter((b) => b.view === "term").map((b) => b.blockid));
+	await adapter.newTab(focusWindowId);
+	const result = await adapter.waitForNewBlock(beforeIds);
+	if (!result) {
+		consola.error("Timed out waiting for new terminal block");
+		process.exit(1);
+	}
+	const { blockId, tabId } = result;
+	await adapter.renameTab(tabId, tabName);
+	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);
+	adapter.closeSocket();
+	return tabId;
+}
+//#endregion
+//#region src/commands/new.ts
+const newCommand = define({
+	name: "new",
+	description: "Open a new tab and launch claude",
+	args: {
+		name: {
+			type: "positional",
+			description: "Tab name"
+		},
+		dir: {
+			type: "positional",
+			description: "Working directory (default: cwd)"
+		},
+		workspace: {
+			type: "string",
+			short: "w",
+			description: "Target workspace"
+		}
+	},
+	async run(ctx) {
+		const name = ctx.positionals[1];
+		const dir = ctx.positionals[2] ?? process.cwd();
+		const workspace = ctx.values.workspace;
+		if (!name) {
+			consola.error("Tab name is required");
+			process.exit(1);
+		}
+		const tabId = await openSession({
+			tabName: name,
+			dir,
+			claudeCmd: "claude",
+			workspaceQuery: workspace
+		});
+		consola.success(`Tab "${name}" [${tabId.slice(0, 8)}] → claude at ${dir}`);
+	}
+});
+//#endregion
+//#region src/commands/resume.ts
+const resumeCommand = define({
+	name: "resume",
+	description: "Open a new tab and run: claude --continue",
+	args: {
+		name: {
+			type: "positional",
+			description: "Tab name"
+		},
+		dir: {
+			type: "positional",
+			description: "Working directory (default: cwd)"
+		}
+	},
+	async run(ctx) {
+		const name = ctx.positionals[1];
+		const dir = ctx.positionals[2] ?? process.cwd();
+		if (!name) {
+			consola.error("Tab name is required");
+			process.exit(1);
+		}
+		const tabId = await openSession({
+			tabName: name,
+			dir,
+			claudeCmd: "claude --continue"
+		});
+		consola.success(`Tab "${name}" [${tabId.slice(0, 8)}] → claude --continue at ${dir}`);
+	}
+});
+//#endregion
+//#region src/core/session.ts
+/** Convert an absolute path to Claude's project slug (/ → -) */
+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);
+	if (!existsSync(projectDir)) return null;
+	const jsonlFiles = 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");
+}
+//#endregion
+//#region src/commands/fork.ts
+const forkCommand = define({
+	name: "fork",
+	description: "Fork a session into a new tab (claude --resume <id> --fork-session)",
+	args: {
+		tab: {
+			type: "positional",
+			description: "Source tab name or ID prefix"
+		},
+		name: {
+			type: "string",
+			short: "n",
+			description: "Name for the new tab"
+		}
+	},
+	async run(ctx) {
+		const sourceQuery = ctx.positionals[1];
+		const customName = ctx.values.name;
+		if (!sourceQuery) {
+			consola.error("Source tab name is required");
+			process.exit(1);
+		}
+		const adapter = requireWaveAdapter();
+		const { tabsById, tabNames } = await adapter.getAllData();
+		const matches = adapter.resolveTab(sourceQuery, tabsById, tabNames);
+		if (!matches.length) {
+			consola.error(`No tab matching '${sourceQuery}'`);
+			process.exit(1);
+		}
+		if (matches.length > 1) {
+			consola.error(`Multiple tabs match '${sourceQuery}':`);
+			for (const tid of matches) consola.log(`  "${tabNames.get(tid)}"  [${tid.slice(0, 8)}]`);
+			process.exit(1);
+		}
+		const tabId = matches[0];
+		const tabName = tabNames.get(tabId) ?? tabId.slice(0, 8);
+		const newName = customName ?? `${tabName}-fork`;
+		const termBlocks = (tabsById.get(tabId) ?? []).filter((b) => b.view === "term");
+		if (!termBlocks.length) {
+			consola.error(`Tab "${tabName}" has no terminal block`);
+			process.exit(1);
+		}
+		const sourceDir = termBlocks[0].meta?.["cmd:cwd"] ?? process.cwd();
+		const sessionId = findLatestSessionId(sourceDir);
+		if (!sessionId) {
+			consola.error(`No Claude session found for ${sourceDir}`);
+			consola.info(`Looked in ~/.claude/projects/${pathToProjectSlug(sourceDir)}/`);
+			process.exit(1);
+		}
+		const newTabId = await openSession({
+			tabName: newName,
+			dir: sourceDir,
+			claudeCmd: `claude --resume ${sessionId} --fork-session`
+		});
+		consola.success(`Forked "${tabName}" → "${newName}" [${newTabId.slice(0, 8)}]`);
+		consola.info(`session: ${sessionId}`);
+	}
+});
+//#endregion
+//#region src/commands/close.ts
+const closeCommand = define({
+	name: "close",
+	description: "Close a tab by name or ID prefix",
+	args: { tab: {
+		type: "positional",
+		description: "Tab name or ID prefix"
+	} },
+	async run(ctx) {
+		const query = ctx.positionals[1];
+		if (!query) {
+			consola.error("Tab name or ID is required");
+			process.exit(1);
+		}
+		const adapter = requireWaveAdapter();
+		const { tabsById, tabNames } = await adapter.getAllData();
+		const matches = adapter.resolveTab(query, tabsById, tabNames);
+		if (!matches.length) {
+			consola.error(`No tab matching '${query}'`);
+			process.exit(1);
+		}
+		if (matches.length > 1) {
+			consola.error(`Multiple tabs match '${query}':`);
+			for (const tid of matches) consola.log(`  "${tabNames.get(tid)}"  [${tid.slice(0, 8)}]`);
+			process.exit(1);
+		}
+		const tabId = matches[0];
+		const name = tabNames.get(tabId) ?? tabId.slice(0, 8);
+		for (const b of tabsById.get(tabId) ?? []) adapter.deleteBlock(b.blockid);
+		adapter.closeSocket();
+		consola.success(`Closed "${name}" [${tabId.slice(0, 8)}]`);
+	}
+});
+//#endregion
+//#region src/commands/rename.ts
+const renameCommand = define({
+	name: "rename",
+	description: "Rename a tab",
+	args: {
+		tab: {
+			type: "positional",
+			description: "Tab name or ID prefix"
+		},
+		newName: {
+			type: "positional",
+			description: "New name"
+		}
+	},
+	async run(ctx) {
+		const query = ctx.positionals[1];
+		const newName = ctx.positionals[2];
+		if (!query || !newName) {
+			consola.error("Usage: herd rename <tab> <new-name>");
+			process.exit(1);
+		}
+		const adapter = requireWaveAdapter();
+		const { tabsById, tabNames } = await adapter.getAllData();
+		const matches = adapter.resolveTab(query, tabsById, tabNames);
+		if (!matches.length) {
+			consola.error(`No tab matching '${query}'`);
+			process.exit(1);
+		}
+		if (matches.length > 1) {
+			consola.error(`Multiple tabs match '${query}':`);
+			for (const tid of matches) consola.log(`  "${tabNames.get(tid)}"  [${tid.slice(0, 8)}]`);
+			process.exit(1);
+		}
+		const oldName = tabNames.get(matches[0]) ?? matches[0].slice(0, 8);
+		await adapter.renameTab(matches[0], newName);
+		adapter.closeSocket();
+		consola.success(`Renamed "${oldName}" → "${newName}"`);
+	}
+});
+//#endregion
+//#region src/commands/scrollback.ts
+const scrollbackCommand = define({
+	name: "scrollback",
+	description: "Show terminal output for a block (default: last 50 lines)",
+	args: {
+		block: {
+			type: "positional",
+			description: "Block ID prefix"
+		},
+		lines: {
+			type: "number",
+			description: "Number of lines to show",
+			default: 50
+		}
+	},
+	async run(ctx) {
+		const query = ctx.positionals[1];
+		const lines = ctx.values.lines ?? 50;
+		if (!query) {
+			consola.error("Block ID is required");
+			process.exit(1);
+		}
+		const adapter = requireWaveAdapter();
+		const blocks = adapter.blocksList();
+		const matches = adapter.resolveBlock(query, blocks);
+		if (!matches.length) {
+			consola.error(`No block matching '${query}'`);
+			process.exit(1);
+		}
+		if (matches.length > 1) {
+			consola.error(`Multiple blocks match '${query}':`);
+			for (const b of matches) consola.log(`  ${b.blockid}`);
+			process.exit(1);
+		}
+		process.stdout.write(adapter.scrollback(matches[0].blockid, lines));
+	}
+});
+//#endregion
+//#region src/commands/send.ts
+function readStdin() {
+	return new Promise((resolve) => {
+		const chunks = [];
+		process.stdin.on("data", (c) => chunks.push(c));
+		process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString()));
+	});
+}
+const sendCommand = define({
+	name: "send",
+	description: "Send input to a tab or block (text arg, --file, or stdin pipe)",
+	args: {
+		target: {
+			type: "positional",
+			description: "Tab name, tab ID prefix, or block ID prefix"
+		},
+		file: {
+			type: "string",
+			short: "f",
+			description: "Read text from file"
+		},
+		enter: {
+			type: "boolean",
+			short: "e",
+			description: "Append newline after text (default: true)"
+		}
+	},
+	async run(ctx) {
+		const query = ctx.positionals[1];
+		const inlineText = ctx.positionals[2];
+		const filePath = ctx.values.file;
+		const appendEnter = ctx.values.enter ?? true;
+		if (!query) {
+			consola.error("Usage: herd send <tab-or-block> [text]");
+			process.exit(1);
+		}
+		let rawText;
+		if (inlineText !== void 0) rawText = inlineText.replace(/\\n/g, "\n").replace(/\\t/g, "	");
+		else if (filePath) rawText = readFileSync(filePath, "utf-8");
+		else rawText = await readStdin();
+		if (appendEnter && !rawText.endsWith("\n")) rawText += "\n";
+		const adapter = requireWaveAdapter();
+		const { tabsById, tabNames } = await adapter.getAllData();
+		const tabMatches = adapter.resolveTab(query, tabsById, tabNames);
+		let blockId;
+		if (tabMatches.length === 1) {
+			const blocks = (tabsById.get(tabMatches[0]) ?? []).filter((b) => b.view === "term");
+			if (!blocks.length) {
+				consola.error(`Tab "${tabNames.get(tabMatches[0])}" has no terminal block`);
+				process.exit(1);
+			}
+			blockId = blocks[0].blockid;
+		} else if (tabMatches.length > 1) {
+			consola.error(`Multiple tabs match '${query}':`);
+			for (const tid of tabMatches) consola.log(`  "${tabNames.get(tid)}"  [${tid.slice(0, 8)}]`);
+			process.exit(1);
+		} else {
+			const allBlocks = adapter.blocksList();
+			const blockMatches = adapter.resolveBlock(query, allBlocks);
+			if (!blockMatches.length) {
+				consola.error(`No tab or block matching '${query}'`);
+				process.exit(1);
+			}
+			if (blockMatches.length > 1) {
+				consola.error(`Multiple blocks match '${query}':`);
+				for (const b of blockMatches) consola.log(`  ${b.blockid}`);
+				process.exit(1);
+			}
+			blockId = blockMatches[0].blockid;
+		}
+		const resp = await adapter.sendInput(blockId, rawText);
+		adapter.closeSocket();
+		if (resp && resp.error) {
+			consola.error(String(resp.error));
+			process.exit(1);
+		}
+		const preview = rawText.slice(0, 80).replace(/\n/g, "↵").replace(/\t/g, "→");
+		consola.success(`Sent to ${blockId.slice(0, 8)}: ${JSON.stringify(preview)}${rawText.length > 80 ? "…" : ""}`);
+	}
+});
+//#endregion
+//#region src/commands/config-cmd.ts
+const configCommand = define({
+	name: "config",
+	description: "Show config file path and current values",
+	args: {},
+	async run() {
+		ensureConfigExists();
+		const config = loadConfig();
+		consola.info(`Config: ${CONFIG_PATH}`);
+		console.log();
+		console.log(`claude.flags    = ${config.claude.flags.length ? JSON.stringify(config.claude.flags) : "(none)"}`);
+		console.log(`defaults.workspace = ${config.defaults.workspace || "(none)"}`);
+	}
+});
+//#endregion
+//#region src/commands/index.ts
+const defaultCommand = define({
+	name: "herd",
+	description,
+	args: {},
+	async run() {
+		await sessionsCommand.run?.call(this, { args: {} });
+	}
+});
+const subCommands = new Map([
+	["sessions", sessionsCommand],
+	["list", listCommand],
+	["ls", listCommand],
+	["new", newCommand],
+	["resume", resumeCommand],
+	["fork", forkCommand],
+	["close", closeCommand],
+	["rename", renameCommand],
+	["scrollback", scrollbackCommand],
+	["send", sendCommand],
+	["config", configCommand]
+]);
+async function run() {
+	await cli(process.argv.slice(2), defaultCommand, {
+		name,
+		version,
+		description,
+		subCommands
+	});
+}
+//#endregion
+//#region src/index.ts
+updateNotifier({ pkg: package_default }).notify();
+run().catch((err) => {
+	console.error(err instanceof Error ? err.message : String(err));
+	process.exit(1);
+});
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@generativereality/herd",
+  "version": "0.1.0",
+  "description": "Agent session manager for AI coding tools. Terminal tabs as the UI, no tmux.",
+  "type": "module",
+  "bin": {
+    "herd": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    ".claude"
+  ],
+  "scripts": {
+    "dev": "bun run ./src/index.ts",
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "check": "bun run typecheck && bun run build",
+    "release": "bumpp && npm publish",
+    "prepack": "bun run build"
+  },
+  "keywords": [
+    "claude-code",
+    "ai-agents",
+    "session-manager",
+    "wave-terminal",
+    "herd",
+    "agentherder"
+  ],
+  "author": "motin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/generativereality/agentherder"
+  },
+  "homepage": "https://agentherder.com",
+  "engines": {
+    "node": ">=20.19.4"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "consola": "^3.4.0",
+    "gunshi": "^0.23.0",
+    "update-notifier": "^7.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/update-notifier": "^6.0.8",
+    "bumpp": "^9.11.1",
+    "tsdown": "^0.12.0",
+    "typescript": "^5.8.0"
+  }
+}