Find specialists with rosters
A roster records who to involve for a purpose and why. The same seat can appear in several
rosters with different capabilities and engagement. Membership is a recommendation, not an
assignment or a grant of authority. Contact someone with the existing rig send or rig queue commands.
Put JSON files in <workspace.root>/rosters/; the included starter and factory leads write
their team's <rig>.json there at first start and never replace an existing one. Read workspace.root with
rig config get workspace.root, or use --folder to read another folder in place.
rig roster list
rig roster show production --json
rig roster find 'colour grading'
rig roster find 'editor@studio' --folder ./rosters --json
list reads authored purposes and curators without contacting daemons. show and find read the
configured daemon and registered HTTP hosts through rig ps. Each command reads current node
listings once per route, not once per member. find matches part of a capability tag or seat
address, ignoring case. A seat in two rosters produces two recommendations with their own reasons.
{
"version": 1,
"id": "production",
"name": "Production",
"purpose": "Make a film",
"curator": { "seat": "lead@studio", "host": "host-a" },
"updated_at": "2026-10-01",
"members": [{
"seat": "editor@studio",
"host": "host-a",
"capabilities": ["colour grading"],
"engagement": ["consult", "review"],
"use_when": "Choose a look or review a grade",
"why": "Knows the footage and the delivery requirements",
"caveat": "Ask about availability first"
}]
}
Use the serving daemon's hostSelfId and the exact seat address from rig ps --nodes -A --json.
A caller's local host alias is not necessarily that identity. Other hosts must already be
registered; the roster command does not register them or dispatch work. Existing HTTP fan-out
reports SSH-only hosts as unsupported. JSON retains per-host failures and partial-read warnings.
Authored files contain recommendations, not runtime facts. Extra fields are ignored, including
any authored runtime, model or activity. At read time the command joins by exact host self-id
and seat. Unmatched or conflicting observations are unknown; a seat not reported running is
stale, with current runtime/model unknown. The configured model is the registry declaration.
Daemon node listings, rig ps --nodes --full and roster members also carry the full
modelObservation: status, model, source, observedAt, generation and reason.
Compact JSON uses the smaller shape described below. The configured model stays separate; roster's
live.observedModel is the observation's model or null. Human output says last observed.
Claude (claude-assistant-response) and Pi (pi-assistant-response) name response evidence;
Codex (codex-turn-context or codex-world-state) names recorded turn configuration, not a
verified backend response. The timestamp is the native record's time, never file mtime or inventory
read time. None promises the model that will answer the next turn.
The daemon reuses the current-occupant record selectors and bounded readers used by divergence monitoring, sharing a process census. Reporting does not need a configured model or comparator. A changed or unverified occupant, a record predating its tenure, missing or invalid record time, unreadable or ambiguous records, unsupported runtimes and older daemons report UNKNOWN with a reason, never the configured value as a fallback. An older record from the same verified occupant remains labelled last observed at its original time; this is not a freshness guarantee. No record contents, transcript paths or credentials are returned. Activity includes its own sample time; activity and running status do not promise that someone is available for new work.
The JSON observations.readAt is when the inventory read completed, not a native observation
timestamp. Rosters are never rewritten by these commands. Malformed files produce warnings while
valid rosters remain usable; duplicate IDs make show report ambiguity instead of selecting one.
Non-regular file targets, such as FIFOs and directories, are skipped with a warning; links to
regular files remain readable. Inventory uses ps --no-cleanup to preserve even stale local
daemon state files. Ordinary rig ps keeps its existing cleanup behavior unless given that flag.
The daemon reuses model facts only while the selected record's identity, size and modification time and the occupant generation remain unchanged. Inventory reads share two bulk pane snapshots and one process census; identity is checked after the final snapshot. A different observation from duplicate host routes makes only that observation UNKNOWN, preserving agreed registry fields.
rig ps --nodes --json keeps an observed model compact as
modelObservation: ["literal-model-id", "evidence-source", "native-record-time"].
UNKNOWN is { "status": "unknown", "reason": "..." }; older daemons may yield
null. --full and --fields modelObservation retain the full object, including
its status and occupant generation. Human output and roster reports use the full
labelled observation.
A member marked "hosted": true is a hosted member: a tool outside the terminal that reaches the team over MCP, with no node or pane.
rig_team lists it with its capabilities and caveat, no pane and activity unknown, unless its seat is one of the rig's nodes.
For a caller on an external grant, a node seat on a roster keeps its own rig_team entry, with that entry's label,
capabilities, use_when, caveat and presence added, so an assistant can see a disconnected seat for what it is. A seat
on no roster reads as before, and so does every seat for an internal caller.
show and find say it's hosted rather than unmatched. See Hosted members.
Its entry can declare wake.webhook, the secret names for a trigger OpenRig rings when work lands for it
(see Ring it when work lands).
It can also declare check_in_minutes, how often it's expected to check its queue (a positive whole number of minutes;
an hourly schedule is 60), or check_in_on_request: true when it checks in only when a person asks it. That's what
its person set up, not something OpenRig observes. With neither, its check-in status reads unknown: OpenRig doesn't
assume a cadence. A value that can't be used doesn't stop the roster loading: that member's check-in
status reads unknown, with the reason. See Check-in status.
Any member can declare a label: how the person knows it, which an assistant can say back, such as
"claude (Sam's assistant, invited)". It's plain text of at most 200 characters, with no control characters, line or
paragraph separators, bidirectional embeddings, overrides or isolates, word joiner or invisible operators (U+2060 to
U+2064), byte-order mark (U+FEFF), or angle brackets. The zero-width space, the zero-width joiner and non-joiner, and
the direction marks are allowed, as names need them. A label that breaks those rules doesn't stop the roster
loading: it's ignored with label_problem, and the member is named by its seat as before. An external caller's entry
carries that label_problem, so an unusable label doesn't read as absent.
A member whose owner says it takes no requests declares takes_requests: false, with an optional takes_requests_note
saying why in plain text (the label rule). rig_team shows it as takesRequests: false and takesRequestsNote on that
entry, so a sender's assistant can choose another before sending. Work sent to it is still written:
rig_queue_create and rig_queue_handoff answer as before, and add requestsAdvisory with the note, so the sender
can send it elsewhere. When some rosters can't be read, or this daemon's host id isn't known yet, requestsAdvisory
says whether it takes requests isn't known, and the write goes ahead. A takes_requests that isn't true or false,
or a note that breaks the label rule or comes without takes_requests: false, doesn't stop the roster loading:
takes_requests_problem says why, and an unusable note leaves the flag in place.
A member can also carry app, which client the participant uses (such as chatgpt, claude, claude-code, codex,
hermes, openrig or studio), and kind, what kind of participant it is (persistent or shared), as the service
that issued its access recorded them. Each is a short lowercase token: a letter, then up to 31 lowercase letters, digits
or hyphens. OpenRig passes the value through as recorded and doesn't keep its own list: the issuing service owns the
values. rig_team shows them as participant: { app, kind } on that member's entry, apart from a seat's own kind
(its node kind). Absent or empty is unknown; neither is inferred from a name or label. A value that isn't a token is
dropped on its own, participant_problem (participantProblem in rig_team) says why, and the roster still loads.
The roster at rosters/network-<rig>.json names that rig's team. Without that file, the roster whose id is the
rig's name does (the <rig>.json the starter and factory leads write; the first by file name if several do). For an
external caller, rig_team reports its name as rig.displayName, beside the rig's own name. The name follows the
label rule; one that breaks it isn't shown, and
rig.displayNameProblem says why. When an external caller's default list of its own open items is empty,
rig_queue_list adds a line its assistant can repeat, such as
No open requests are addressed to you on the team "Sam's team". (a list of every state says No requests …).
If the owner hasn't named the team, the name is Your OpenRig team, and the line says on your OpenRig team. Without
that roster, or with a name that can't be shown, there's no display name, and the line says on your OpenRig team.
Labels, names and caveats are as the roster's writer last authored them, not live observations. Presence is OpenRig's
own reading. When some rosters can't be read, or this daemon's host id isn't known yet, rig_team says so in
hostedMembersNote: hosted members, and the roster entries of the team's seats, may be missing. The seats themselves
are still listed.