Skip to content
All work

Agents and tools

Agent Orchestrator

Runs a coordinator and several headless coding agents in parallel, each in its own worktree.

Internal toolNo public link

Parallel coding agents collide. They share ports, databases and branches, and they stop without saying so.

The orchestrator gives each worker its own git worktree, port and backend deployment, has the driver write heartbeats instead of trusting the model to, and keeps a merge queue so one pull request lands at a time. Agents plan, implement, open pull requests and review each other. A person clicks merge.

Status
Used to develop Anvil. Internal, not packaged for others.
Stack
Bash, git worktrees, Claude Code, GitHub CLI

Why it exists

Interactive coding sessions wait for a keystroke, so a run can stall with nothing left to do but a git push.

Agents sharing one backend can erase each other's tables. Skipped CI jobs can look like passes. Running several agents at once turns small problems like these into lost work, so the orchestrator is built to keep them apart and keep them moving.

Try it

Three simulated workers, one merge queue. This is an illustrative prototype built for this site with fictional data, not the product itself.

Agent lanes · Illustrative prototype · fictional data

One run through it

  1. Set up the run

    Each worker gets its own branch, worktree and port.

  2. Plan first

    A worker writes its plan and stops. The coordinator approves through its inbox.

  3. Build

    The worker implements while a scanner checks file ownership on every tick.

  4. Open a pull request

    The worker opens it and parks.

  5. Peer review

    Another finished worker reviews it once, at a frozen commit, in a throwaway worktree.

  6. Merge

    A person clicks merge.

What it does

  • Coordinator and workers

    Claims, inboxes and an event log in a shared run directory.

  • Isolation

    A worktree, a port and a separate backend deployment per worker.

  • Heartbeats from the driver

    Liveness comes from the loop around the model, not from the model.

  • Merge queue

    When a merge lands, the next worker rebases. Pull requests are never stacked.

  • Peer review

    Workers review each other's pull requests before a person sees them.

Why it's built this way

  • Headless runs in a shell loop

    Each turn is a headless run inside a loop, so nothing ever sits waiting on a keystroke.

  • The driver writes the heartbeat

    The loop writes it during turns, so a long-running model never looks idle.

  • The base commit is derived

    It comes from git merge-base at read time, so workers don't get blamed for commits they inherited.

How it fits together

  1. 01Bash drivers wrapping headless Claude Code sessions in loops.
  2. 02Base commits computed at read time with git merge-base, never stored.
  3. 03A test suite that runs against fake CLI binaries.

In plain terms

Git worktree
A separate working folder on its own branch.
Heartbeat
A regularly refreshed "still alive" record.
Merge queue
Changes landing one at a time.
Rebase
Replaying a branch onto a newer main.
Headless
Running with no interactive session, so nothing waits for a person to type.

Related