What it is

It is built to be built on. One machine or ten, a tool above it sees one roster, one address space and one set of actions; the network is rosterd's problem. The vision.

Three surfaces, one truth

What it refuses to do

The boundaries are the product. rosterd never:

• reads prompts, transcripts or terminal screens;
• infers activity from time, CPU or output;
• schedules or wakes an agent on its own, there is no timer;
• stores task or decision history;
• dials a client, holds a client's URL, token or ids;
• binds to anything but loopback and the Tailscale interface.

Anything that keeps a record over sessions, a project board, a task runner, a workspace, is a client of the API and only a client. It pulls the roster, subscribes to changes, answers through the action endpoints, and maps sessions to its own ids on its side.

Install

# macOS: the release bottle, a LaunchAgent and the tray
brew tap sbusso/rosterd https://github.com/sbusso/rosterd && brew trust sbusso/rosterd
brew install rosterd && brew services start rosterd

# Linux: the release tarball, a systemd user unit
tar xzf rosterd-<ver>-x86_64-unknown-linux-gnu.tar.gz
rosterd-<ver>/packaging/install.sh --from rosterd-<ver>/dist/x86_64-unknown-linux-gnu

# Arch, from source
makepkg -si -p packaging/arch/PKGBUILD

# then, on every machine: hooks, ACP adapters, the tray at login, a swarm to join
rosterd setup

rosterd setup is one row per thing the machine needs: binaries on PATH, config, the service, per harness its binary, adapter and hooks, the tray, and optionally a swarm. Space picks, enter runs, --yes runs it headless. It is the only step that edits ~/.claude and ~/.codex.

The brick and the connector.

rosterd is deliberately small: one daemon per machine that tells the truth about agent sessions, can drive them, and hides the network. Anything built on top sees one roster, one address space and one set of actions, whether there is one machine or ten.

Independent by design

Nothing points up. rosterd holds no URL, token or id of anything that uses it, never dials out, and keeps no history a client could depend on. A client is anything with an HTTP client and a bearer: it pulls a snapshot, follows the change stream, and answers through a handful of POSTs. Replacing a client costs rosterd nothing; replacing rosterd under a client costs the client nothing, because the record is versioned, additive, and unknown fields are ignored.

That independence is the point, not a constraint. A daemon that reads no transcript can run on every machine, including the one with the client secrets. A daemon that schedules nothing lets the tool above own timing and policy. A daemon with no database has nothing to migrate, back up or reconcile. A daemon that never dials out needs no per-client configuration and cannot leak to the wrong place.

The mesh, abstracted

A tool never addresses a machine. It addresses a session, by key or by name, and asks any node. Which machine owns it, whether that machine is reachable, how the request gets there and how the answer comes back, is rosterd's business: discovery over the tailnet, membership by invite and gossip, one signed snapshot stream per peer, actions proxied to the owner with the sender's signature, a lost peer served dimmed from its last snapshot. From above, a swarm of ten looks exactly like one node with more rows.

The same abstraction runs in the other direction. A harness does not know it is on a mesh either. Hooks post to a local socket; ACP flows through a local holder; the MCP server is a local socket. Nothing in a harness's configuration mentions another machine.

Control workflows live on top

rosterd ships four activity words and five actions, on purpose. Every richer behaviour is composed above it, by a tool that owns its own rules, and each tool can be different. An approval workflow that only allows git push after the test session reports idle with a green recap is thirty lines against the contract, and nothing inside rosterd had to learn what a test is:

# any language with an HTTP client; here, the shape of it
for event in sse("/swarm/changes"):
    if event.name != "attention" or event.record.activity_event != "permission": continue
    key, pending = event.record.session_key, get(f"/sessions/{key}").pending
    if not (pending.tool == "Bash" and "git push" in pending.summary):
        continue                                        # a human answers everything else
    tests = get(f"/sessions/tests:{event.record.name}")  # the sibling by name, wherever it runs
    ok = tests.activity == "idle" and "passed" in tests.recap
    post(f"/sessions/{key}/permission", option="allow" if ok else "reject")

The same shape gives a board its attempts, a runner its queue, a bot its notifications, a coordinator its delegation, a dashboard its spend. Each keeps its own state, on its own side, in its own ids. rosterd keeps the roster.

Where it goes

Architecture

One binary, six modules, and a small holder process per headless session. Everything a node knows is in memory and rebuilt in under a second from holders, hook claims and a process scan.

Inside a node

The roster answers even when the runner is wedged: rosterd list and watch read the roster module only. The mesh reads the roster to serve peers and writes peer snapshots beside it, never into it. Every node is the only writer of its own roster, which is why the swarm needs no merge.

Process model

rosterd owns no harness process directly. A headless session is holder → ACP adapter → harness. The holder is a separate small binary shipped with rosterd; it starts the adapter with stdio pipes, listens on a per-session socket under the runtime directory, relays JSON-RPC both ways unchanged, keeps a replay buffer of the last 256 notifications, and writes a state file with the session id, harness, cwd, adapter PID and start time. On start rosterd lists the holder directory, reconnects to every live holder, replays the buffer and rebuilds those sessions.

This is what makes the daemon disposable. Kill it during a turn, restart it: the session is still live, the turn completes, no claim is lost.

The swarm

The record

One record per session, schema rosterd.snapshot.v1. Consumers ignore unknown fields. Nested processes of one session collapse into the root; a harness whose parent is a different session is its own record with parent_session_key.

Cross platform

Linux reads /proc and runs as a systemd user unit; macOS reads libproc and runs as a LaunchAgent in the GUI session so open reaches the display and the tmux server; Windows uses toolhelp, named pipes and a service, with an interactive lane of hooks only. The holder, the hook script and the opener are the only platform-conditional code.

Data and event flows

A session's state is a series of claims. Each claim names a source, an activity word, an event and a sequence; the roster accepts or rejects it by precedence and publishes the whole table. Everything downstream is derived from that.

Sources and precedence

A lower source never overwrites a value a higher one set, but every source can fill a null. A headless session has both acp and hook; when they disagree, ACP wins. rosterd explain KEY shows which source set each field and which claims were rejected and why: the truthfulness view.

ACP traffic to activity

Plan, mode and context fill ride along: plan replaces the whole list on every notification, current_mode_update sets mode, usage_update fills usage. The final assistant message of a turn is kept as the recap when the session was started with recap: true; nothing else of the transcript is stored.

A permission, answered from the phone

Every client sees the same thing because every client reads the same record. A board that keeps its own decision log reads the pending request from GET /sessions/{key} and answers it the same way; the tray answers it with a click; the CLI with rosterd allow KEY. Sound, badges and urgency stay the client's job.

The change stream

GET /swarm/events is one full swarm snapshot per change anywhere: simplest to consume, heavy to notify on. GET /swarm/changes is the diff, computed by the node between consecutive frames, so a client learns what happened instead of re-reading the roster:

Pure function of two frames, derived and never stored. rosterd changes prints it one line per change; attention is the one to notify on.

A client that would rather be called than hold the stream open registers a webhook: POST /hooks {url, events, token}. Every matching event then arrives as one POST, {event, data}, with the name in X-Rosterd-Event and the token as a bearer. rosterd keeps the URL and nothing else about the caller. A failed delivery is dropped, and the client catches up from the last seq it saw with /swarm/changes?since=.

Session lifecycle

The runner never resumes on a timer. There is no wake-up schedule; a suspended session comes back only when something addresses it: a prompt from the CLI, the MCP tool or a client, or rosterd resume. On reboot every headless session is restored as suspended, none is resumed until addressed. Resumes are counted per hour; past max_resumes_per_hour a session stays suspended with a warning.

Restart, crash, reboot

• rosterd restart. Holders keep running. The roster rebuilds in under a second from holder state, replayed notifications, hook claims and a scan. Nothing is lost.
• Holder or harness crash. The scanner notices the PID is gone; the session ends with reason crash. With a stored session id the runner resumes it once through session/load in a new holder, as a new key with the same session id. A second crash within five minutes is not resumed.
• Machine reboot. Holders are gone. The state files left behind restore each session as suspended.

Use cases

What people actually do with it, and the parts of rosterd each one leans on.

What it can do, how, and what comes next

One page, top to bottom: the capabilities of a node, the way each one is built, and the directions the swarm opens. Sections marked new are landing now.

See

$ rosterd list --swarm
gibson   3 active  1 idle  1 needs attention        reachable
mbp      1 active  1 suspended                      reachable
arch     2 idle                                     stale 41s

api: swarm changes   claude  needs_attention  4s   headless     gibson  84560
board: puller        claude  active           58s  interactive  gibson  71022
[finance]            codex   idle             4m   interactive  gibson  61840
docs: pages site     claude  active           1s   headless     mbp     3341
migrate: holders     claude  suspended        2h   headless     mbp     -

Act

Run

1. POST /sessions (or rosterd start) with harness, cwd, name, model, effort, policy and env. The runner starts a holder, the holder starts the adapter, ACP initialize and session/new run, the session id is stored, the record registers with sources acp and launcher.
2. The launch environment carries ROSTERD_SOCKET, so hooks inside the harness post claims too; ACP wins when they disagree. The rosterd MCP server is in the harness's config under the name rosterd.
3. Turns flow: prompt, message chunks, tool calls, permission requests, plan and mode updates, usage, turn end. Each becomes a claim with a sequence.
4. Idle past idle_timeout_s: the holder is stopped, the record stays suspended with its session id. A pending permission keeps the session live because it cannot survive the harness.
5. The next prompt starts a new holder, session/load with the stored id, waits for it to settle, delivers the prompt. The caller sees one call that takes a little longer.

Policy auto approves every permission and stays active; attention leaves it pending. A child spawned through session.spawn inherits the parent's policy unless the call overrides it. Codex and pi join through their own adapters; pi's extension supplies the claims and the gate the adapter lacks.

Federate

A swarm is nodes that answer for each other. Join with an invite, then rosterd list --swarm on any machine is the union roster and any action on a session owned elsewhere is proxied to its owner with the sender's signature. Membership and revocations gossip in every hello. A peer off the tailnet is served from its last snapshot, dimmed, with its age; back on, the stale snapshot is replaced. Nothing else changes when a peer is unreachable, and nothing waits on one.

Learn new

Hand off new

A headless session is portable: its harness session id, cwd, name and policy. rosterd handoff KEY --to NODE suspends it on the owner, ships the holder state to the target over the mesh, and resumes it there under a new key with the same session id. The repo has to exist on both sides; that is the caller's business, rosterd checks the cwd and refuses otherwise. Laptop to desktop before a long run, desktop to server before closing the lid.

Agents talking to agents new

The MCP server already lets a session spawn children and prompt them. session.send completes the loop: address any session in the swarm by name, wait until it is idle, read its recap. Two agents on two machines can hand each other work with the roster as the address book, and rosterd still schedules nothing: every prompt is sent by someone, a human or an agent, never by a timer.

# from inside a session, through the rosterd MCP server
session.spawn      { harness: "claude", cwd: "~/Code/rosterd", name: "tests: holder" }
session.send       { name: "tests: holder", prompt: "run the relay tests", wait_until: "idle" }
session.read_state { name: "tests: holder" }      → { activity: "idle", recap: "3 passed…" }

Opportunities

API, MCP, CLI

All JSON, all on the local socket and the loopback listener with a bearer token; the swarm paths also on the Tailscale listener. Every CLI command with --json prints the API frame for its resource byte for byte.

Endpoints

The session paths are the same under the loopback listener and, prefixed with the owning node, over the swarm. Any node accepts an action for any session and proxies it; the response travels back.

MCP tools

Served on the same socket under the name rosterd, in the config of every harness started by the runner or the launcher. The caller is identified by its PID from the socket peer credentials.

CLI

rosterd list|watch [--swarm|--node N]      one row per session; watch reprints on every change
rosterd changes                            one line per change across the swarm
rosterd status | nodes                     this node; swarm membership and health
rosterd read KEY | explain KEY             one session in full; which source set each field
rosterd start --harness H --cwd DIR [--name L] [--policy auto|attention] [--model M] [--effort E] [--env K=V]
rosterd prompt KEY TEXT [--wait idle|needs_attention|ended] [--timeout SECONDS]
rosterd cancel|stop|suspend|resume|open KEY
rosterd name KEY LABEL | name KEY --clear
rosterd allow KEY [--always] | deny KEY [--reason TEXT]
rosterd spawn KEY --harness H --cwd DIR [--name L]
rosterd handoff KEY --to NODE
rosterd usage [--swarm] [--since 7d] | journal [--since T]
rosterd invite [--ttl MINUTES] | join ADDRESS --token T | revoke NODE_ID | leave
rosterd integrate install|uninstall claude|codex|pi | integrate status
rosterd ui | daemon [--config PATH] | setup [--yes] | doctor | version

KEY is an exact session key, a PID on this node, or a unique display name; an ambiguous name lists the candidates and never guesses. Exit codes: 0 ok, 1 user error, 2 daemon unreachable, 3 a peer was needed and is unreachable. The agent-facing summary is skill/SKILL.md; its one rule: never parse the human tables.

Config

# ~/.config/rosterd/rosterd.toml on Linux, ~/Library/Application Support/rosterd/ on macOS
[node]
name = "gibson"              # pinned; a renamed machine is a new name, the id stays
port = 8791                  # the swarm listener, on the Tailscale interface
listen = "tailscale"
loopback_port = 8790         # the page and local tools, bearer in loopback.token

[swarm]
static_peers = ["100.64.0.12:8791"]   # the fallback without Tailscale

[runner]
default_permission_policy = "attention"
idle_timeout_s = 1800
suspend_on_needs_attention = false
resume_on_crash = true
max_resumes_per_hour = 6
recap = true

[sources]
files = false
scan_interval_ms = 2000

[harness.claude]
adapter = "claude-agent-acp"
[harness.codex]
adapter = "codex-acp"
[harness.pi]
adapter = "pi-acp"
extension = true
gate_timeout_s = 3600

Keys and tokens live next to it with mode 0600: node.key, loopback.token, swarm.json. Adapters are pinned by version, pi's by commit, in a lock file the node writes on first install.

Hooks

rosterd setup or rosterd integrate install claude writes these; only marked entries are ours, everything else in the file is kept. The hook reads session_id, hook_event_name, cwd and notification_type, nothing else, posts the claim to the socket, fails open in 800 ms and always exits 0.

{ "hooks": {
  "SessionStart":      [{ "hooks": [{ "type": "command", "command": "rosterd-hook" }] }],
  "UserPromptSubmit":  [{ "hooks": [{ "type": "command", "command": "rosterd-hook" }] }],
  "PreToolUse":        [{ "matcher": "", "hooks": [{ "type": "command", "command": "rosterd-hook" }] }],
  "PermissionRequest": [{ "hooks": [{ "type": "command", "command": "rosterd-hook" }] }],
  "Notification":      [{ "hooks": [{ "type": "command", "command": "rosterd-hook" }] }],
  "Stop":              [{ "hooks": [{ "type": "command", "command": "rosterd-hook" }] }]
} }

Environment