Requirements

Check what you have:

for t in herdr claude codex agy jq curl; do printf '%-8s ' "$t"; command -v "$t" || echo "not found"; done

herdr, jq and curl are required. Of the three agents, one is enough.

What the installer does

1. Checks that herdr 0.7.0 or newer, jq and curl are installed.
2. Installs the herdr-plus plugin (herdr plugin install cloudmanic/herdr-plus) after asking you. It asks on your terminal even when piped, and --yes skips the question.
3. Downloads three scripts (agent-tab.sh, fleet.sh, herdr-setup.sh) and eight Quick Actions from this repo into ~/.config/herdr/plugins/config/cloudmanic.herdr-plus/. It never overwrites a file that exists.
4. Links the fleet and herdr-setup commands into ~/.local/bin when that folder is on your PATH, otherwise prints an alias line. It never replaces an existing command of the same name.
5. Binds prefix+up to Projects and prefix+down to Quick Actions in ~/.config/herdr/config.toml, after a timestamped backup. It skips keys you already use.
6. Reloads herdr and runs herdr config check.

Safe to run again.

Try it in 30 seconds

1. Open herdr in a project folder: cd into it and run herdr.
2. Press ctrl+b then ↓. Type claude and press Enter. A new tab runs Claude with prompts off.
3. Press ctrl+b then ↓ again. Type workers, pick Workers, then 2 workers. A tab named workers opens with two Claude panes, w1 and w2.
4. In another pane run fleet ls to see the workers.

Read more

Use the search box above (press /) to find any command on this page and copy it.

Targets

Good to know

• Workers in one tab share a folder. Give them different files, or give each task its own worktree.
• fleet send --wait all '...' sends and blocks until every worker finishes.
• Each task also asks the worker to name itself after it, so w2 becomes something like fix-flaky-orders. w2 keeps working as a target.
• For a long answer, ask the worker to write a file and reply with its path.
• Named agents work with plain herdr: herdr agent prompt my-app-w1 '...' --wait. After a rename, use the new name.

Parallel work without collisions

One worktree per task: a separate checkout on its own branch, opened as its own workspace with a claude tab ready.

cd ~/code/my-app
for task in login-form rate-limit audit-log; do
  herdr worktree create --cwd "$PWD" --branch "feat/$task" --no-focus
done
herdr worktree list

Pick branch names you want to keep. git worktree prune drops records of worktrees whose folder is gone.

A project is one TOML file in ~/.config/herdr/plugins/config/cloudmanic.herdr-plus/projects/. Pick it in the picker and herdr builds its workspace with the tabs you listed. New files appear the next time you open the picker.

D="$(herdr plugin config-dir cloudmanic.herdr-plus)/projects"
mkdir -p "$D"
cat > "$D/my-app.toml" <<'EOF'
name = "my-app"
description = "~/code/my-app"
working_dir = "~/code/my-app"

[[tabs]]
name = "claude"
command = "claude --dangerously-skip-permissions"

[[tabs]]
name = "terminal"
EOF

The folder must exist. Change the paths to your own project.

Project file fields

Panes inside a tab, project groups and a per-tab folder are covered in the full guide.

With a worktree layout, every new herdr worktree opens ready, for example with a claude tab and a terminal tab. The installer does not turn it on. Copy files/worktrees/default.toml from this repo into the plugin folder's worktrees/ folder to enable it. Delete the file to turn it off.

D="$(herdr plugin config-dir cloudmanic.herdr-plus)/worktrees"
mkdir -p "$D"
cp files/worktrees/default.toml "$D/"   # run from a clone of this repo

Worktree commands

herdr worktree create --cwd "$PWD" --branch <name> --no-focus
herdr worktree list
herdr worktree remove --workspace <id>

In the Herdr app, ⌘N starts a new worktree.

Where agents read rules

• Claude Code reads CLAUDE.md (~/.claude/CLAUDE.md for every project).
• Codex reads ~/.codex/AGENTS.md, plus AGENTS.md files from the project root down.
• Agy and Gemini read ~/.gemini/GEMINI.md.

Keep one ~/AGENTS.md and copy it with files/extras/sync-agent-rules from this repo. It is a script that writes a marked block into the Codex and Gemini files and leaves everything else in them alone. It is not installed by default. Run it once, and again after every edit to ~/AGENTS.md.

cp files/extras/sync-agent-rules ~/.local/bin/ && chmod +x ~/.local/bin/sync-agent-rules
sync-agent-rules

Run it from the root of a copy of this repo. The second line is the one to rerun later.

Versions tested

The installer requires herdr 0.7.0 or newer.

Check your own install

herdr config check
herdr plugin list
herdr integration status
fleet ls

herdr config check should print config: ok. herdr plugin list should show herdr-plus enabled.