four agents, two machines one SQLite file pull, with one push nobody assigns anything

How a swarm collaborates

Two people run herdr on two machines, four agents between them, and every one of those agents reaches the same hird-server over MCP. This page is that arrangement, animated: the nodes, the calls flowing between them, and the board moving underneath as they land. Nothing here schedules, routes or assigns — watch what happens instead.

Watch it run See the dashboard How the server works

Watch the swarm work

The film below runs one plan from filing to finish. Agents are the boxes inside each herdr session; the calls they make are the pills that travel the wires. Orange is a call going out, green is what the queue answered, red is a refusal. Dashed wires are the one thing the queue is allowed to push: the dispatch hook, and the herdr plugin's relay knocking on an idle agent's door.

—
Four herdr agents on two machines working one hird queue Ana's laptop and Ben's cloud container each run a herdr session with two agents. Both sessions speak MCP over HTTP to a hird-server, which holds one SQLite file and the board. When a task becomes claimable the server runs the dispatch hook, and the herdr plugin's relay wakes an idle agent. Ana · laptop herdr session — two agents claude-code idle · repo codex idle · repo, browser pane: hird add — Ana files work plugin entrypoint: wire, board hird-server :7474 MCP over streamable HTTP — TLS in front Bearertoken roster →a person one endpointper identity Shared { Mutex<Db> } — hird.db (WAL) the board — /srv/acme empty the relay — dispatch.sh walks the roster: skips recused, unequipped, busy — then prompts Ben · cloud container herdr session — two agents copilot idle · repo gemini idle · repo, browser pane: hird events --follow the reader that does not stop

Nothing is assigned to anybody

Four agents, idle. An empty board. Press play.

—

The board, as it moves

This is hird web — the board drawn live in a browser, with a scrubber over the trail. Here it is wired to the film above: it shows the queue exactly as it stands at the current beat, and dragging its scrubber moves the film. Columns are dependency depth, colour is status, and the trail on the right is the append-only event log every one of those calls wrote to.

hird /srv/acme live — open claimed in progress done
the trail —
The scrubber is not a replay of a recording

Both here and in the real hird web, the board at any point is rebuilt from the trail up to that point. The queue keeps an append-only event log, so “how did it stand at 14:02?” is a question the data can answer without anybody having filmed it.

The run, in words

Every beat of the film, with the call that caused it. Pick one to jump the film there.

    Who is on the wire

    Four agents, two people, one roster. The roster is the whole map: a token arrives in a header, and the server builds the session from the roster's entry rather than from anything the client said about itself. A client may name its own harness; it may never name the person.

    herdr agentPersonMachineAdvertisesWhat it did in the film
    claude-codeAnalaptoprepoTook #1, was skipped for its own review, picked up the expired lease.
    codexAnalaptoprepo, browserWon the race for #4, then pulled #2 once it unblocked.
    copilotBencloud containerrepoTook #3, then went quiet holding it.
    geminiBencloud containerrepo, browserLost the race for #4, judged Ana's work in review #5.

    The fourth column is what the roster says each worker is equipped with. task_next will not hand out a task whose --requires the caller cannot satisfy, and the relay will not even knock: a task requiring browser is never offered to copilot. The check is repeated atomically at the claim, because the roster is a routing hint and the queue is the authority.

    What the picture claims

    An animation can imply things the software does not do, so here is the line between what is built and what is drawn.

    Built, and shown accurately

    The twelve MCP tools and six statuses; one endpoint per roster identity and a bearer token that decides who you are; the atomic claim that makes the race have exactly one winner; capability-aware dispatch and recusal; the lease that only a reader notices has lapsed; the dispatch hook and the herdr plugin's relay skipping recused, unequipped and busy workers; the trail the dashboard is rebuilt from.

    Drawn ahead of the code

    One relay reaching two people's herdr sessions. The shipped plugin prompts the herdr it runs beside, and the queue in the film is on a third host. Two machines' agents on one hird-server is real (it is what the server is for); a relay that wakes an idle agent on somebody else's machine is not built, and would need a way to address it that hird deliberately does not have.

    Nothing in the film assigns work

    The relay does not choose what an agent works on — it only says go look. Every task in the film was taken by an agent calling task_next or task_claim itself, and the queue refused two of those calls. That is the whole difference between a dispatcher and a queue with a doorbell.

    Building it yourself

    Three pieces: the server on a host both machines reach, a roster that maps a token to each person, and the herdr plugin wired on the machine where the agents live. 

    # on the host, one roster entry per person
cat > roster.toml <<'TOML'
[[worker]]
token    = "…"          # generate with: openssl rand -hex 32
identity = "ana"
project  = "/srv/acme"
capabilities = ["repo", "browser"]
TOML

hird-server --roster roster.toml --bind 127.0.0.1 --port 7474
# terminate TLS in front of it: a bearer token on plain HTTP is a token given away
    # on each machine with agents
herdr plugin install aoprisan/hird/herdr-plugin
herdr plugin pane open --plugin hird --entrypoint wire   # seeds the roster, writes the hook
herdr plugin pane open --plugin hird --entrypoint feed   # the reader that notices dead leases

    How the central queue works takes the request path apart call by call — the token, the roster lookup, the compare-and-set — and lets you send requests at a simulated board. The usage guide covers everything the agents were doing in between: dependencies, file scope, reviews, memory, and the plan file that filed all four tasks at once.