Parallel Work

Your tangible win

After this lesson, you can set up a safe parallel review: one Herdr workspace, an isolated Git worktree, a helper agent in its own pane, and a result you can inspect without stealing focus from the main task.

One project, many places

Herdr's layout primitives compose from broad to narrow: a workspace contains tabs, a tab contains panes, and a pane may contain an agent or an ordinary terminal process.

Why worktrees matter

Two agents in two panes can still collide if they edit the same checkout. A worktree gives a parallel branch its own directory while Herdr keeps it visible as a normal workspace.

Create an isolated checkout

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

Herdr creates the Git checkout, opens it as a workspace, and groups it with the parent repository workspace. To attach to an existing checkout without creating another one:

herdr worktree open \
  --cwd ~/project \
  --branch feature/review \
  --no-focus

Build the layout before starting the agent

agent start does not create or split panes. First create the workspace or tab, capture the returned root pane, and split only when you need another terminal.

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"

The --no-focus flag matters in orchestration: create the helper without yanking the user's current view away from the main task.

Give the helper a bounded job

Use an explicit scope and output contract. A good handoff names the checkout, permitted paths, validation command, and required report.

herdr agent prompt reviewer \
  "Review only src/api and tests/api. \
  Do not edit files. Run the focused tests. \
  Report findings by severity and include paths." \
  --wait \
  --timeout 120000

Then read the result without relying on the state badge alone:

herdr agent read reviewer \
  --source recent-unwrapped \
  --lines 120

Use the state machine for handoff

For agents, use agent wait; for ordinary servers and test runners, use pane wait-output. They solve different problems.

herdr agent wait reviewer \
  --until idle \
  --until done \
  --until blocked \
  --timeout 120000

Move a live pane carefully

A pane move can change its workspace-qualified pane ID. Capture and use the new ID from the response. A running process keeps its launch-time Herdr environment, and --current remains safe from inside that process.

moved=$(herdr pane move w1:p2 \
  --new-workspace \
  --label "Review handoff" \
  --no-focus)
printf '%s\n' "$moved" | jq \
  '.result.move_result | {previous_pane_id, pane}'

Checkpoint: choose the isolation boundary

1. You need two agents to work on two branches of the same repo.
2. Create a worktree for each branch.
3. Open each worktree as a Herdr workspace.
4. Start one agent in a pane per workspace.
5. Give each agent a bounded prompt and a verification command.
6. Wait, read, and review before merging either result.

Remember this

Build the place first, isolate the checkout when branches diverge, start the agent second, and hand off with a bounded scope plus proof requirement.