@generativereality/agentherder 0.1.6 → 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.6",
+  "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.6";
+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}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@generativereality/agentherder",
-  "version": "0.1.6",
+  "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
@@ -103,28 +103,25 @@ use `herd resume <name> <dir>` afterwards to open the resulting session in a new
 
 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):
+**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
-# 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
+herd new payments ~/Dev/myapp --prompt "implement the billing endpoint"
+herd new payments ~/Dev/myapp --file /tmp/task.txt
 ```
 
-Once Claude is ready, send the task:
+If you need to send a task after the fact, poll first:
 
 ```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
+herd new payments ~/Dev/myapp
+# 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