Workflow: Parallel Agents

Fresh

This is the main Herdr workflow: start several agents, let them work in parallel, and use the sidebar to see which project needs a decision, which one is still running, and which one is ready to review.

flowchart TD
    A[Create one workspace per project] --> B[Start an agent in each]
    B --> C[Agents work in parallel]
    C --> D{Sidebar state}
    D -->|blocked| E[Jump to pane, answer the prompt]
    D -->|working| F[Leave it alone]
    D -->|done| G[Review the result]
    E --> C
    G --> H[Next task or close workspace]

Setup

1. Give each active project its own workspace (prefix+shift+n). This keeps agent state readable in the sidebar.

2. Start an agent in each workspace's root pane:

claude

Herdr detects supported agents automatically.

3. Optional: use Git worktrees for parallel work on one repo. From a Git workspace row in the sidebar, New worktree creates a branch and checkout, opens it as a new workspace, and groups it under the source workspace. Or from the CLI:

herdr worktree create --workspace 1 --branch worktree/api --no-focus

Triage with state rollups

The sidebar rolls state upward: a blocked agent makes its pane, tab, and workspace look blocked. A working agent makes the workspace look active. A done agent stays visible until you view it.

State	Meaning	Your move
blocked	Needs input, approval, or a decision	Jump there now
working	Actively running	Nothing
done	Finished, not yet seen	Review when ready
idle	Finished or waiting, already seen	Nothing

Jump to agents with prefix+alt+1..9 (if bound) or click them in the sidebar.

Get notified instead of watching

Enable toasts when agents finish or need input:

[ui.toast]
delivery = "herdr"
delay_seconds = 1

Use delivery = "terminal" over SSH so your local terminal owns the notification, or delivery = "system" for OS notifications. Sound notifications are on by default ([ui.sound] enabled = true).

Detach and walk away

Detach with prefix+q. All agents keep running in the background server. Reattach with herdr and check the sidebar for anything that went blocked or done while you were gone.