You are inside herdr (a terminal multiplexer) where several AI agents run in parallel, one per project. This skill is the fleet launcher: it gives each live agent-tab its own conductor — a manager split in beside the agent, in its tab, that reads the session, decides what's next, asks the human scored questions in-pane, and drives the existing agent via herdr — fanning independent work into parallel worktree lanes. One manager per tab — never one brain juggling all sessions.
The manager's behavior lives in the herdr-pm-agent skill, which this launcher installs and mounts. You (the launcher) only discover, set up, spawn, and hand off. (herdr-pm-agent is also independently invocable — a human can point it at a single tab without going through this launcher; it then self-bootstraps. This skill is the multi-tab front door.)
When to use / not
- Use when you have running herdr agent sessions and want them supervised/driven by PMs.
- Not for the per-tab logic itself → that is
herdr-pm-agent(mounted automatically). - Not for a one-off Codex side-task → use
claude-to-codex. - Not outside herdr → if
HERDR_ENVis unset, stop and say so.
Prerequisites
HERDR_ENV=1 and herdr status --json shows a running, compatible server. You cannot start herdr from bash (it needs a TUI) — if it is down, tell the user. Scripts live in this skill's scripts/ dir, referenced below as $HPM/scripts where HPM="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/skills/herdr-pm-init" (the plugin root when installed as a plugin, else the ~/.claude/skills pool).
Workflow
1. Discover the live agent-tabs
python3 "$HPM/scripts/discover_and_spawn.py" discover
Returns JSON: backends_available (offer only CLIs that exist), manage (live agent-tabs with ids, workspace label/number, session, cwd, foreground cwd, repo_root when git can resolve it, and has_conductor — true = a PM already sits in that tab: list as "already managed", never spawn a second), skip_conductors (your own PMs — filtered by registered pm-* name when Herdr exposes it, with fixed ◆ PM … pane labels as the durable fallback), skip_executors (ex-* lanes), skip_idle (empty panes, fully addressable — report, don't manage). Ids are opaque strings: copy them verbatim, never construct one. Detail → references/launcher-workflow.md.
2. Confirm scope with the human
Show the detected agent-tabs; let the human mark which to manage — via your host's interactive question tool (Claude → AskUserQuestion; Codex → request_user_input when available, otherwise an active numbered prompt in-pane; never a passive plain-text list the human must type against). Default = live tabs only (crash-restore of dead sessions is out of scope — offer it only if asked). If a tab is ambiguous, ask.
3. Setup questions — exactly two, one batched ask
Peek at each chosen session first, then ask context-aware questions — options from each project's actual work, not a fixed menu:
- Manager backend — ask as
[conductor] will manage [managed](e.g.claude will manage claude,codex will manage claude); default codex. - Autopilot — render as ASCII bars, not digits (
▰▱▱▱ observe · ▰▰▱▱ consult · ▰▰▰▱ autonomous(default)· ▰▰▰▰ full); frame around the project's risky/safe steps. The assignment carries the level number.
Never ask about: mode — auto-detect it ([ -d <repo>/.herdr-pm ] → power, else light; a human can opt a fresh repo into power by saying so, but it is not a question you raise). Placement — every conductor splits side-by-side into its managed agent's tab; there is no other mode. Relay rhythm — gone; humans answer PMs in their tabs. Codex reviews — not a setup question; the conductor offers them just-in-time on its first branch/worktree review when ~/.codex exists. Goals / the mandate — not a launcher question; in POWER the conductor runs its own deep onboarding interview ("why did you hire me?") on its first turn. This is exactly why launcher setup stays at two questions: you place the hire, the hire learns the job.
4. Codex question-tool preflight (only if any conductor backend is codex)
Before spawning a codex conductor, make sure its default/code mode can actively ask the human:
codex features list | grep -E '^default_mode_request_user_input[[:space:]]+' || true
If it is not true, ask the human through your current host's active question tool: "Enable Codex request_user_input in default/code mode so PM conductors can ask scored questions directly?" If they approve, run:
codex features enable default_mode_request_user_input
Then re-check codex features list. This edits the user's Codex config intentionally and may require a fresh codex session/restart for already-running Codex panes; new conductors spawned after the change should see it. If the human declines or the command is unavailable, continue with the documented active numbered-prompt fallback.
5. Install the operator skill (before spawning — backends scan skills at startup)
HPM="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/skills/herdr-pm-init"
python3 "$HPM/scripts/install_agent_skill.py" --name herdr-pm-agent \
--src "${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/skills/herdr-pm-agent" --scope global \
--backends codex --dry-run # review, then drop --dry-run
Only codex needs this — claude/pi/hermes already see the operator via the canonical ~/.agents/skills pool. Install global (avoids dropping a symlink + skills-lock.json into the repo). Per-backend dirs + invocation (/name claude, $name codex) → references/backend-matrix.md.
6. Mode is auto-detected; scaffold + charter a fresh, explicitly-requested power world
[ -d <repo>/.herdr-pm ] → spawn with --mode power --cwd <repo>/.herdr-pm (the world already exists — no question, no re-init). Otherwise --mode light --cwd <repo>, unless the human explicitly asked for power — only then gather a 1–2 sentence mandate (the north star + win-condition; ask one scoped question if unclear — not a long interview) and scaffold:
python3 "$HPM/scripts/init_power_world.py" --repo <repo> --slug <slug> \
--managed-pane <pane> --managed-term <term> --session-id <sid> \
--autopilot <N> --language <lang> \
--goal "<the 1-2 sentence mandate you gathered>" # writes GOAL/00-charter.md
init_power_world.py builds the full canonical world (spec → herdr-pm-agent references/power-world.md): the folders (GOAL/ TODO/ PLAN/ DECISION/ LEARNING/ MEMORY/), the projection fixtures (STATE/DIGEST/RUNLOG), MEMORY/INDEX + drive-facts, the PLAN/ planning fixtures, a pointers-only hub AGENTS.md (folder map + read-order + plan-first — it does NOT defer to a long interview), and GOAL/00-charter.md from your --goal. On its first power turn the conductor just confirms the mandate (one light touch) and drives (herdr-pm-agent → references/onboarding-interview.md §1). If you couldn't gather a mandate, omit --goal — the charter lands PENDING and the conductor captures it in one question. Git-ignored. Re-running init on an existing world is safe — it completes a partial one (idempotent fill, clobbers nothing), --check audits it, --upgrade refreshes a stale hub; --force is a full reset (fresh only). Several PMs on one repo → --world-dir .herdr-pm-<role> per PM, then spawn with --world (auto-detect stays exactly .herdr-pm). Detail → references/launcher-workflow.md.
7. Spawn one manager per tab (serial by default)
One script call per conductor — it splits the conductor side-by-side into the managed agent's tab and runs the whole atomic flow (split-start → registration wait → fixed pane-label rename ◆ PM <REPO_UPPER> + read-back verify → best-effort 70/30 resize → write + prime the assignment → resend-if-eaten → auth check), emitting one JSON result. Tabs are never renamed; the conductor's pane label is fixed after spawn, and live state uses custom_status:
python3 "$HPM/scripts/discover_and_spawn.py" spawn \
--slug <slug> --backend <claude|codex|pi|hermes> \
--cwd <repo-or-.herdr-pm> --repo-upper <REPO_UPPER> \
--managed-pane <pane> --managed-term <term> --session-id <sid> \
--repo <repo> --mode <light|power> --autopilot <N> --language <lang>
Check "ok": true and every verify.* flag; layout_70_30 is informational, not a gate. On auth_ok: false, the script closes only the conductor pane and reports closed_conductor_pane; keep the managed agent's tab. The assignment lands at ~/.local/state/herdr-pm/<slug>/assignment.md (durable — never /tmp), carries your_term, notes $HERDR_PANE_ID for self-targeted status updates, and (power, optional) --world; pane ids still renumber, so any rare pane operation must re-resolve first (references/pitfalls.md #4/#20). Never spawn the next conductor until this one's JSON came back ok. Raw per-step commands (fallback / debugging) → references/backend-matrix.md; traps → references/pitfalls.md.
8. Hand off — the PMs talk to the human directly
Each conductor sits beside its agent and asks the human in-pane (custom_status: awaiting you plus one best-effort notification means a decision is waiting). Your job after spawning: report the spawn results + which conductors already await a decision, fire one summary toast (notification show "PMs ready" …), then get out of the way. A conductor is self-sufficient: it dispatches missions via pm.py dispatch --file (each minting a unique marker — TASK_DONE reuse false-fires, pitfall #28; parallel worktree lanes for independent work), arms a backgrounded dual-arm wait (minted-marker wait primary + agent wait <managed_term> status secondary — terminal id, never a pane id; references/pitfalls.md #23) and self-wakes, verifies, reports — you don't babysit it. On request you can survey all conductors (board digest) or answer a conductor's widget for the human via pm.py keys (#19); re-poke one only as a fallback if it stalls past its wait. Conductors keep a short, stable ◆ PM <REPO_UPPER> pane label and never rename tabs. Survey + live autopilot change → references/launcher-workflow.md.
9. Offer monitor mode (optional — the manager-of-managers loop)
After hand-off, offer to stay on as an autonomous fleet supervisor for a window the human sets through the host's active question tool: "Enter monitor mode for [duration]? I'll keep the whole fleet moving with zero blockers — auto-recover freezes / rate-limits / codex-limits / hung-shells, and auto-answer every PM question with full autonomy (a fresh decision sub-agent reads both scrollbacks and picks the most momentum-forward option). PAUSE anytime via touch ~/.local/state/herdr-pm/PAUSE." If yes → read references/monitor-mode.md and follow it: store the deadline → start the deterministic floor (scripts/monitor-loop.sh, backgrounded) → arm the read-only Monitor (pm_monitor.py --watch) → arm a 4-min ScheduleWakeup heartbeat, then run the per-wake loop. Within the window the human's grant is full autonomy — every action (incl. prod deploy / force-push / delete / migration / spend) is pre-authorized; never leave a blocker. If no → you're done at Step 8. The detector script: pm_monitor.py --dry-run (human report) · --json (orchestrator snapshot) · --watch (the Monitor tripwire) · default ACT (the floor).
Decision rules
- One manager per tab; isolated context. Don't consolidate sessions unless the human asks (offer it only for clearly-similar repos, with a before→after tab-rename preview).
- Install (codex only) before spawn — global by default (no repo pollution); claude/pi/hermes need no install (canonical pool). Project scope is an explicit opt-in.
- Spawn serial by default; offer a wave only if the human wants speed over a calm question flow.
- Pass minimal context at spawn (ids + mode) and let the operator skill carry the how — don't inline the whole method.
- On a re-run, mode auto-detects (
.herdr-pm/exists → power) and.herdr-pm/AGENTS.mdpre-fills autopilot — re-ask only backend if relevant. Skip executors too: discovery'sskip_executors(ex-*panes) are a conductor's parallel lanes, never manageable agents. - Stay in the human's language; never hardcode one.
Guardrails
- Never change the human's focus or active window — not even to "restore" it. Every
herdr tab create/agent startuses--no-focus; all conductor reads and waits run in the background. Never callherdr tab focus/pane focus/agent focus/pane zoom|swapautomatically: if the human navigated to a pane themselves, leave it — they own focus and the view entirely. Never runherdr update,server stop|reload-config,session, orintegrationcommands — infra is the human's. - Never use
--currentor omit a target id in automation — omitted targets resolve to the human's focused pane/workspace, not yours (pitfall #27). Explicit--pane/--workspace/--cwd, always. - Confirm the conductor is actually alive, not just spawned. After priming, read the pane and verify the operator skill loaded AND there is no auth/login error (e.g.
token_revoked, "sign in again"). A backend can spawn, goworking, then die on auth — if so, fall back to another backend. - Outside herdr (
HERDR_ENVunset) or herdr down → stop, explain, do not improvise. - Never clobber a real skill dir on install (the script reports
skip-real); never edit a tracked.gitignore(power world uses.git/info/exclude). - SKILL.md
descriptionhas a hard 1024-char ceiling — codex enforces it, claude doesn't. Over it, codex prints⚠ invalid description: exceeds maximum length of 1024 characters, skips loading the skill, and the warning surfaces on every codex pane. Re-measure after ANY frontmatter edit; both this skill (~996) and herdr-pm-agent (~972) already hug the ceiling, so trim before adding. Symptom + measure command →references/pitfalls.md#32. (It caps only the description — the body is unbounded, so put detail there.) - Re-resolve pane ids from
terminal_id— they renumber (references/pitfalls.md). - The managers do the project work; you set them up and relay. Don't start editing project code yourself.
- Monitor mode is full-autonomy by design (
references/monitor-mode.md): within the user-set window the orchestrator auto-answers every question and takes any action — including irreversible/prod ones — without a second ask; the window IS the authorization. The only brakes are the PAUSE file (~/.local/state/herdr-pm/PAUSE) and a human typing in a pane (took-the-wheel). Stay the single in-session writer; run one--watchat a time (watch.lock); resolve ids at call time; two-phase consequential widget keys.
Reference routing
| File | Read when |
|---|---|
references/launcher-workflow.md |
Running discovery, the setup-question shaping, install, and the per-tab spawn loop end to end. |
references/backend-matrix.md |
Spawning/installing/invoking a specific backend (claude/codex/pi/hermes) — exact commands + JSON keys. |
references/pitfalls.md |
Any herdr/codex spawn-or-drive trap (pane renumbering, done≠idle, lost sends, reserved names, plain-text reads). |
references/monitor-mode.md |
Running the autonomous fleet-supervisor loop (Step 9 / "monitor mode"): the --watch/--json flags, the ScheduleWakeup+Monitor wake loop, the full-autonomy decision sub-agent, the hung-shell (ESC×2) + recovery playbook. |