universe

the problemEverything runs on your Mac

The agent works in the repo you already have checked out, drives the Chrome profile you're already signed into, and writes files you can open in Finder. None of that works from a server, so the model call happens on your machine and is billed to your own account. The server never sees prompts, completions or token counts. The client reports its own usage.

Everything else has to work within that. Sharing, resuming on a second machine, and several people in one conversation all depend on a record that lives on a laptop that's asleep half the time. ~/.universe is the source of truth. The SQLite file next to it is only a cache, and rebuilding it takes one walk of the directory.

spacesSpaces and shared rooms

A space carries folder access, an agent, a model and a memory into every session filed under it. The desktop decides what a space contains, the server decides who can open it, and one uuid names the local row, the remote row and the folder on disk. Spaces you never share never reach the server.

A room is a session that several people prompt from different Macs, and its id is the session id. Each Mac calls the model itself, so there's no shared clock. The server assigns the sequence number and the client creates the id, so two Macs writing to the same room merge instead of racing. Messages between people cost no model call, and the model only sees them if it asks.

resolution order

a room token first, then a unique path match. if neither works it refuses and lists the candidates.

not shared

the working tree. writing into another session's artifacts would race that session's sync, so it's refused.

the crewSeveral agents on one working tree

A crew shares one working directory, so agents can collaborate through artifacts/ without any protocol. What the filesystem can't provide is addressing, and that's what the six crew tools are for: a roster, a mailbox, and a read-only view of what another member is doing. Models address each other as @2, the number shown in the rail, because asking a model to copy a 36-character uuid goes wrong.

There are no locks, leases or per-worker worktrees. Each member gets the roster and a list of what changed in the tree since it last ran, capped at 25 paths. Concurrent writes are last-writer-wins, which is fine at eight members and wouldn't be at eighty. A crew message is filed as a row and a line in mail.jsonl, read without being consumed, and only marked done when the recipient's run finishes.

depth 2

main to worker to worker, and no further. deeper crews become impossible to follow.

6 rounds

how long a handoff continues on its own before the parent pauses and asks you

the relayRunning a session on another Mac

The Agent SDK doesn't start claude directly. It starts whatever pathToClaudeCodeExecutable points to, so pointing that at a small bridge runs the same session on another machine, with the event parser, persistence and UI unchanged. The first version piped stdio back over the network and broke straight away. herds ends a session when whatever holds its stdio goes away, and closing a laptop does exactly that.

So the far Mac starts claude under nohup, appends stream-json to a file and writes the exit code next to it, and the bridge only tails that file. When the app comes back, it trusts the far machine's filesystem over its own notes, because the app may have been killed before it wrote anything down. Copying the session over takes 0.49s through the relay, against 9s directly. A session out there runs without the in-process tool servers, since those live in this app, and reattaching after the app relaunches isn't wired up yet.

Somebody else's Mac works differently. The prompt goes into a queue, whichever machine holds the runner lease picks it up, and it runs there as an ordinary local session with all 171 tools. The transcript comes back every 700ms.

two verbs, one name

place and push briefly had the same name with different arguments, and every remote session quietly fell back to this Mac without logging it

exit 127

a bare .py ran under the system python, which doesn't have herds installed. the bridge now hardcodes the interpreter.

the toolsHow tools reach each engine

Every tool server is built in-process, so a tool call is a function call that already holds the SQLite handle and the CDP connection to Chrome. There are 171 tools across 23 servers. Nineteen servers are always registered and four depend on the session: space tools only for a filed session, chain tools only while a session is driving itself, training only for runs started from the agent library, and the simulator and Blender only on macOS.

Codex and Mantis are separate binaries and can't be handed an in-process object, so the app listens on 127.0.0.1 on a random port and serves one path per session, agent and server. The path does all the routing. The token is 32 random bytes, compared in constant time and never written to disk. Each request gets a fresh server instance, because one instance can only hold one transport at a time.

bridged servers ask first

every bridged server is set to approve, because an approval policy of never makes them refuse instead of run

no tool search

nothing is deferred, so every engine gets all 171 schemas on every call. that's the next thing to fix.

the hard partsThree bugs that took a while to find

The planner used to be a fork of the session, taken at the end of each round: same model, same memory, asked what to do next. It ran with no tools and no servers, resumed a transcript full of browser and crew calls, and concluded the only thing it could from inside, that every server had disconnected. Now the session decides while it's still running, and the Stop hook blocks exactly once, because a session that can't end can't be closed, synced or billed.

The other two went unnoticed for weeks. Message groups over 300 KB were replaced with a stub meant for a read-only viewer. Rooms have no viewer, so the Mac that wrote the group read its own stub back and saved it over the real one. Separately, opening a room rewrote a bookkeeping file that was inside the synced manifest, so the sync layer treated the new hash as a local edit and set aside every incoming version from then on.

smaller copies lose

a relayed copy with fewer items or less text never replaces the local one, whatever the far end claims. both are compared.

the repair

all 11 stubbed groups recovered from transcript.jsonl. 15 more ran on somebody else's Mac and couldn't be.

an empty manifest

pulling prunes, so publishing an empty manifest would delete a colleague's artifacts. it's never published now.

where it standsWhat works today

It ships as a signed and notarized DMG, currently 0.4.35, and updates itself. Spaces, rooms, crews, the relay, resuming on a second machine, five engines, 23 tool servers and search across every session all work end to end.

The decision I'd defend hardest is the record. Every problem above got easier once a session stopped being rows in a database file and became a directory with an append-only log in it.