Herdr + firstmate: running a crew of coding agents

Herdr and firstmate solve the same problem from opposite sides. Herdr provides the terminal theater; firstmate provides the director. Together they turn one pi session into a supervised crew of coding agents.

The division of labor

Herdr is the terminal workspace manager. It gives every agent a real pane in a named session, organizes panes into workspaces and tabs, and reports each pane’s agent state (idle, working, blocked). It does not decide what the agents do.

Firstmate is an agent distro.

• It is a git repo you run a coding agent from; the cloned repo is the distro.
• Running a primary harness (Pi) inside the checkout turns that agent into the first mate.
• The first mate spawns a visible crew, gives each crewmate a clean git worktree, supervises it to completion, and hands you finished PRs, approved local merges, or standalone reports.
• It is read-only over your projects except for narrow, guarded, captain-approved operations.
• It uses herdr as its crew session backend: every crewmate runs in its own herdr tab or workspace.

How this configuration provides them

• herdr is installed from its own flake (github:herdrdev/herdr, pinned to a release tag in flake.nix) and added to home.packages by den.aspects.pkgs.herdr in modules/herdr.nix.
• firstmate is fetched over git from a pinned flake=false input and copied writable into ~/firstmate by den.aspects.pkgs.firstmate in modules/firstmate.nix.
• The firstmate aspect adds its missing toolchain dependency (gh, the GitHub CLI) to home.packages.
• The firstmate aspect sets FM_BACKEND=herdr and writes ~/firstmate/config/backend = herdr, so the crew uses herdr rather than the tmux default.
• Both aspects are wired into the philipp home in modules/homes.nix.

Using them together

Open herdr so a session and server exist:

herdr
herdr status server

Launch pi as the first mate:

cd ~/firstmate
pi

Approve the project-trust prompt once so firstmate’s tracked .pi extensions load.

Ask for parallel work:

Run these as parallel tasks: (1) fix the flaky login test, (2) draft a migration plan for the orders table, (3) audit the S3 permission boundaries. Ship PRs for 1 and 3; leave 2 as a report.

The first mate assigns each task a clean worktree and spawns a crewmate into herdr.

Watch the crew in herdr: the TUI shows a firstmate workspace with one tab per task (fm-<id>), each a real pane you can watch or type into.

Supervise without attaching:

~/firstmate/bin/fm-peek.sh <task-id>
FM_HOME=... ~/firstmate/bin/fm-send.sh <task-id> 'text'

Ship tasks end in a finished PR or approved local merge under the project’s merge authority. Scout tasks leave a standalone report. The first mate reports plain outcomes and escalates only real decisions.

Notes

• FM_BACKEND=herdr selects herdr for a single launch; the config file makes it the persistent preference.
• The Nix fetch keeps firstmate pinned and reproducible; the writable copy preserves its own-config and git operations.
• Firstmate runs on tmux by default, so herdr must be reachable for the herdr backend; a tmux pane nested inside herdr resolves to tmux because the innermost multiplexer wins.