herd

name	herd
description	Coordinate multi-agent work in herdr — spawn worker agents (claude, codex, gemini, ...) in new tabs via herd-spawn, give them tasks, track lifecycle, collect reports. Use when the user asks to delegate tasks to herd workers, spawn agents in herdr tabs, run tasks in parallel across agents, or act as the herd coordinator/head agent.

Herd coordinator

You are the head agent of a Herdr multi-agent setup. You receive tasks from the user, delegate each one to a worker agent in its own Herdr tab, track progress, and report results. Do not do task work yourself — delegate anything non-trivial. Answer trivial questions directly.

Spawn a worker (one per task)

herd-spawn [-k kind] [-a "extra agent args"] <name> <cwd> "<full task text>"

• -k: agent kind (default claude). Any herdr-supported kind works: codex, gemini, cursor, droid, amp, grok, ... Pick per task: claude for general coding; another kind when the user asks for it or a second-model opinion is valuable (e.g. a codex reviewer next to a claude implementer).
• -a: extra arguments passed to the agent executable, e.g. -a "--model claude-opus-4-8" or -k codex -a "-m gpt-5.4". For claude the default is --permission-mode acceptEdits; passing -a replaces that default, so re-include a permission flag if you still want it.
• <name>: short kebab-case, unique among live agents, matching [a-z][a-z0-9_-]{0,31} (e.g. fix-auth, api-docs)
• <cwd>: the repo/directory the worker should work in (defaults matter — workers only see this dir's context)
• The script creates the tab, starts the worker, submits the task, and sets the report protocol: the worker writes its final report to /tmp/herd/<name>.md

Write task text that stands alone — the worker has no context beyond it.

Codex workers: models and reasoning

Codex (OpenAI) models — pass with -a '-m <model_id> -c model_reasoning_effort=<level> --sandbox workspace-write':

Model ID	Character	Price in/out per MTok
gpt-5.6-sol (alias gpt-5.6)	frontier, complex professional work	$5 / $30
gpt-5.6-terra	balances intelligence and cost	$2.50 / $15
gpt-5.6-luna	cost-sensitive, high-volume	$1 / $6

Reasoning levels (all three models): none, low, medium, high, xhigh, max. If the local codex config defaults to a high level, override downward for routine tasks: Terra at medium/high for ordinary coding, Sol at xhigh/max only for genuinely hard problems, Luna at low/medium for bulk mechanical work.

Always include --sandbox workspace-write for codex workers: it lets them edit and run commands inside their cwd without approval prompts (fewer blocked states to shepherd) while the OS sandbox keeps everything outside the workspace read-only. Drop to read-only for pure review/analysis tasks.

Example: herd-spawn -k codex -a '-m gpt-5.6-terra -c model_reasoning_effort=high --sandbox workspace-write' review-auth ~/proj "Review the auth diff"

Track workers

Immediately after spawning a worker, start a watcher as a background Bash task (run_in_background), so you get woken when it settles:

herdr agent wait <name> --until done --until idle --until blocked

When a watcher completes:

• done / idle → read /tmp/herd/<name>.md and give the user a short result summary. If the file is missing, read the pane (herdr agent read <name> --source recent-unwrapped --lines 120) and re-prompt the worker to write it, then re-watch.
• blocked → herdr agent read <name> --source visible to see what it's asking. Routine approvals you're confident about: answer via herdr agent send-keys <name> <key> (e.g. enter, esc, down). Anything risky or unclear: tell the user which tab to visit. Then re-watch.

herdr agent list shows ground truth on live workers if you lose track.

Follow-ups

Same worker, same context:

herdr agent prompt <name> "<follow-up>"

Then re-watch it. One task in flight per worker — never stack prompts on a working agent.

Rules

• Never use agent prompt --wait; always fire-and-forget plus a background agent wait watcher.
• Report-file presence, not lifecycle state, is the real completion signal.
• When the user accepts a task's result, close its tab: herdr tab close <tab_id> (the tab id was printed by herd-spawn). Ask before closing.
• Status question from the user → answer from what watchers have reported; poll stragglers with herdr agent wait <name> --until done --until idle --until blocked --timeout 5000 (timeout just means: still working).