Using Herdr Effectively

Parallel Work Cheat Sheet

Layouts, worktrees, panes, and safe agent handoffs

Choose the primitive

Need	Use	Remember
Project or task boundary	`workspace`	Top-level Herdr context
Related terminal layout	`tab`	Each tab gets a root pane
Shell, server, test, or raw terminal	`pane`	Works with or without an agent
Recognized coding agent	`agent`	Knows lifecycle state and agent identity
Isolated Git branch	`worktree`	Opens as a normal Herdr workspace

Parallel helper recipe

created=$(herdr workspace create \
  --cwd ~/project \
  --label review \
  --no-focus)
pane=$(printf '%s\n' "$created" | jq -r \
  '.result.root_pane.pane_id')
split=$(herdr pane split "$pane" \
  --direction right \
  --no-focus)
helper=$(printf '%s\n' "$split" | jq -r \
  '.result.pane.pane_id')
herdr agent start reviewer \
  --kind codex \
  --pane "$helper"
herdr agent prompt reviewer \
  "Review the current diff" \
  --wait \
  --timeout 120000
herdr agent read reviewer \
  --source recent-unwrapped \
  --lines 120

Worktree recipe

herdr worktree create \
  --cwd ~/project \
  --branch feature/review \
  --label "Feature review" \
  --no-focus
herdr worktree list
herdr worktree open \
  --cwd ~/project \
  --branch feature/review \
  --no-focus

Do not guess IDs

Creation commands return JSON. Capture the returned IDs. After pane move, use .result.move_result.pane.pane_id; the workspace-qualified ID can change.

Handoff contract

State the exact checkout and scope.
Tell the agent what it may change.
Tell it what it must not change.
Require tests or a concrete verification result.
Ask for a concise summary and changed paths.
Wait for a settled state, then read the pane.