OpenRig User

This is an as-built guide to the shipped rig CLI. Use current code and rig ... --help as ground truth if anything here ever conflicts with older planning docs.

This is the daily-driving CLI guide for an OpenRig operator. It is not a guide to OpenRig internals or to changing OpenRig behavior — for that, work in the openrig product repo.

Runtime-Gated Coordination Primitives

OpenRig v0.2.0 is published publicly as @openrig/[email protected] and GitHub Release v0.2.0. It includes the bundled PL-004 Coordination Primitive System: Phase A rig stream / rig queue, Phase B rig project / rig view, Phase C rig watchdog, and Phase D rig workflow / workflow-keepalive.

Do not confuse public package truth with this host's active daemon truth. As of 2026-05-04, the human reports the production daemon has been upgraded to v0.2.0; a local check showed rig --version and the product package version at 0.2.0, with the daemon running on port 7433.

Default posture on this host now:

• Treat daemon rig queue, rig stream, rig project, rig view, rig watchdog, and

rig workflow as active-host coordination surfaces for PL-004-backed work.

• CANONICAL SURFACE NOTE (2026-05-11): rig queue (daemon-backed SQLite) is the

canonical surface for queue routing since the 2026-05-11 host-CLI fix landed. Use rig queue create / handoff / update / show / list for all substantive work.

• Use substrate rigx queue, rigx stream, rigx project, and rigx view-proto only where the

current workflow is still explicitly operating on the temporary substrate coordination layer or a legacy artifact has not migrated. For queue specifically, rigx queue is recovery-only fallback; qitems written via rigx queue are invisible to daemon-backed reads and break fleet-wide routing discipline.

• If a daemon-backed coordination command fails, debug the command/runtime/schema edge directly;

do not fall back to stale pre-upgrade assumptions about this host.

• Do not run daemon stop/start, wrapper mutation, production DB copy/mutation, git push, tags, npm

publish, or GitHub release unless a human grants the specific bounded gate. The public release already exists; further release operations need explicit scope.

Core Loop

Most work in OpenRig reduces to this loop:

• recover identity: rig whoami --json
• inspect inventory: rig ps --nodes --json
• read context: rig transcript ..., rig ask ..., rig chatroom history ...
• act: rig send, rig capture, rig broadcast, lifecycle commands

Identity and Recovery

Start here after launch, compaction, or confusion:

rig whoami --json

What it gives you today:

• identity: rig, logical ID, pod/member, session name, runtime
• peers and directional edges
• transcript info
• contextUsage when available

Flags:

rig whoami --session <name>
rig whoami --node-id <id>

If the daemon is unreachable but identity can still be inferred, --json may return a partial result instead of crashing.

Inventory and Monitoring

rig ps
rig ps --json
rig ps --nodes
rig ps --nodes --json

Use rig ps --nodes --json for the current node inventory across rigs. It is the best machine-readable operator surface for:

• session name
• runtime
• session/startup status
• restore outcome
• attach/resume commands
• latest error

Other health surfaces:

rig status
rig daemon status
rig config
rig preflight
rig doctor

Transcript and Communication

Transcript access

rig transcript <session> --tail 100
rig transcript <session> --grep "pattern"
rig transcript <session> --json

Send to one session

rig send <session> "message"
rig send <session> "message" --verify
rig send <session> "message" --force
rig send <session> "message" --json

Use --verify when you want delivery evidence. Use --force only when you intentionally want to bypass activity-risk checks.

Observed operator nuance for --verify:

• Sent to ... + Verified: yes = strong positive delivery evidence.
• Sent to ... + Verified: no = ambiguous delivery, not automatic failure. We have repeatedly seen the message still land; treat this as verification drift until disproven.
• no Sent to ... line or a hard error = send failure.

When you get Verified: no, do not immediately retry blindly. First check one of:

• a direct reply from the target
• rig capture <session>
• transcript evidence
• queue/outbox state if the message asked for a durable handoff

Capture terminal output

rig capture <session>
rig capture <session> --lines 50
rig capture --rig <name>
rig capture --pod <name> --rig <name>
rig capture --rig <name> --json

Capture discipline:

• Default to bounded captures: rig capture <session> --lines 80.
• Use --lines 120 when the latest activity is ambiguous.
• Use --lines 200 or more only for explicit recovery/debug reconstruction, such as post-compaction restore, context-wall diagnosis, or a failed handoff.
• Prefer targeted rig transcript <session> --tail ..., rig transcript <session> --grep ..., queue files, or status commands over large pane captures.
• Do not use large captures as routine monitoring; they waste operator context and can hide the actual latest state in old scrollback.

Broadcast

rig broadcast --rig <name> "message"
rig broadcast --pod <name> "message"
rig broadcast "message"
rig broadcast --rig <name> "message" --json

Without --rig or --pod, broadcast targets all running sessions.

Chatroom

rig chatroom send <rig> <message> [--sender <name>]
rig chatroom history <rig> [--topic <name>] [--after <id>] [--since <ts>] [--sender <name>] [--limit <n>] [--json]
rig chatroom wait <rig> [--after <id>] [--topic <name>] [--sender <name>] [--timeout <seconds>] [--json]
rig chatroom clear <rig>
rig chatroom topic <rig> <topic-name> [--body <text>] [--sender <name>]
rig chatroom watch <rig> [--tmux]

Key commands:

• send — post a message
• history — retrieve with composable filters (sender, since, after, topic)
• wait — block until new matching messages arrive (polls history, times out honestly)
• clear — delete all messages for the rig (destructive, rig-scoped)
• topic — set a topic marker
• watch — SSE or tmux-based live stream

Roundtable protocol:

1. Inspect old room: rig chatroom history my-rig --limit 5
2. Save if needed: rig chatroom history my-rig --json > /tmp/old-room.json
3. Clear if needed: rig chatroom clear my-rig
4. Set topic: rig chatroom topic my-rig "ROUND START"
5. Post: rig chatroom send my-rig "position..." --sender <session>
6. Monitor: rig chatroom wait my-rig --timeout 120
7. Close: rig chatroom topic my-rig "ROUND CLOSED"

See docs/planning/roadmaps/chatroom-roundtable-protocol.md for the full protocol.

rig ask

rig ask <rig> "question"
rig ask <rig> "question" --json

Current shipped behavior:

• queries the daemon for evidence
• returns rig summary
• returns transcript excerpts
• may return chat excerpts
• returns insufficiency state and optional guidance

This is an evidence/context command. It is not a hidden second-LLM call.

Lifecycle

Bring a rig up

rig up <source>
rig up <source> --plan
rig up <source> --yes
rig up <source> --json

<source> can be:

• a rig spec path
• a .rigbundle path
• a bare name

Bare names are special:

• if they match a library spec, rig up launches from the spec library
• if they do not match a library spec, rig up treats the name as an existing-rig restore/power-on target
• if both exist, rig up fails loudly on ambiguity

Current behavior notes:

• --target <root> is only for .rigbundle / package installation. It does not change agent cwd.
• local: agent_ref values resolve relative to the rig spec directory, not your shell cwd.
• if you copy a built-in spec elsewhere, keep its agents/ tree beside the YAML or rewrite those refs to path:/absolute/path
• rig up --cwd <path> exists as a launch working-directory override applied to all members for that run (verify with rig up --help)
• Source at OpenRig 6af2754 adds member-level starter_ref for named Agent

Starter registry entries. Active host availability still depends on the running daemon; rig-real-17812d5 does not resolve starter_ref.

Legacy/spec-specific surfaces still ship too:

rig bootstrap <spec> [--plan] [--yes] [--json]
rig requirements <spec> [--json]

Agent Starter starter_ref

Source >= 6af2754 lets a RigSpec member set:

starter_ref:
  name: my-team-starter--claude-code

The daemon resolves the named entry from the Agent Starter registry, applies the credential scan, and prepends the starter content as guidance_merge on fresh launch. It supports Claude and Codex members, rejects terminal members, rejects starter_ref + session_source.mode: fork, and allows starter_ref + session_source.mode: rebuild.

Runtime-truth rule: verify active daemon/runtime provenance before depending on this. If the live daemon is still rig-real-17812d5, starter_ref is source truth only and should not be used against the active control plane. After a runtime at or after 6af2754 is active, rig up --plan --json should expose a resolve_starter stage with detail.starterContent.

Tear a rig down

rig down <rig>            # <rig> = rig name or id (active rig)
rig down <rig> --snapshot
rig down <rig> --delete
rig down <rig> --force
rig down <rig> --json

rig down accepts a rig name or id (symmetric with rig up); the earlier name-to-404 caveat is resolved in v0.3.3. An ambiguous name matching more than one active rig is refused with the matching ids; re-run with rig down <id>.

If --snapshot succeeds, human output includes the restore hint.

Release management without killing live claimed sessions

rig release <rigId>
rig release <rigId> --delete
rig release <rigId> --json

Use rig release for adopted/claimed-session rigs when you want OpenRig to stop managing the rig but leave the tmux sessions alive. This is the safe recovery/reset surface for the "sessions still exist, management is broken or stale" case. If the rig contains OpenRig-launched nodes, rig release refuses loudly instead of pretending the mixed rig is safe to detach.

Snapshots and restore

rig snapshot <rigId>
rig snapshot list <rigId>
rig restore <snapshotId> --rig <rigId>

rig restore requires --rig <rigId>.

Claude Code autonomy note:

• unattended rig whoami on boot may require the local permission allow list to include Bash(rig:*)

Import/export and bundles

rig export <rigId> -o rig.yaml
rig import <path> [--instantiate] [--materialize-only] [--preflight] [--target-rig <rigId>] [--rig-root <root>]
rig bundle create <spec> -o out.rigbundle
rig bundle inspect <bundle>
rig bundle install <bundle> [--plan] [--yes] [--target <root>] [--json]

Legacy package surface

This still ships, but is explicitly marked legacy:

rig package validate <path>
rig package plan <path> [--target <dir>] [--runtime <runtime>] [--role <name>]
rig package install <path> [--target <dir>] [--runtime <runtime>] [--role <name>] [--allow-merge]
rig package list
rig package rollback <installId>

Discovery and Topology Mutation

Discover unmanaged tmux sessions

rig discover
rig discover --json
rig discover --draft

Bind a discovered session

rig bind <discoveredId> --rig <rigId> --node <logicalId>
rig bind <discoveredId> --rig <rigId> --pod <namespace> --member <name>

There is no shipped top-level rig claim command. The current adoption surface is discover, bind, adopt, and unclaim.

Self-attach the current shell or agent

rig attach --self --rig <rigId> --node <logicalId>
rig attach --self --rig <rigId> --node <logicalId> --print-env
rig attach --self --rig <rigId> --pod <namespace> --member <name> --runtime <runtime>

Use rig attach --self when the current agent should attach itself directly instead of going through discover + bind.

Current proven behavior:

• inside tmux: attaches as a normal tmux-backed node, preserving inbound rig send / rig capture
• outside tmux: attaches as external_cli
• --print-env prints the OPENRIG_NODE_ID and OPENRIG_SESSION_NAME exports for the current shell

Recommended flow:

rig attach --self --rig <rigId> --node <logicalId> --print-env > /tmp/openrig-self-attach.env
. /tmp/openrig-self-attach.env
rig whoami --json

Notes:

• for tmux-backed self-attach, rig whoami --json is the right verification
• for raw/external self-attach, rig ps --nodes --json is currently the more reliable verification surface
• if the current shell is outside tmux, pass --display-name <name> when you want a stable human session label recorded

Adopt a topology and bind live sessions

rig adopt <path> --bind <logicalId=tmuxSessionOrDiscoveryId>
rig adopt <path> --bind <logicalId=...> --bind <logicalId=...> --json
rig adopt <path> --bindings-file <bindings.yaml>
rig adopt <path> --bind <logicalId=...> --target-rig <rigId> --rig-root <root>

Use rig adopt when the sessions already exist and you want OpenRig to start managing them.

A bindings file is the durable map from authored logical IDs to live sessions. Shape:

bindings:
  dev1.impl2: dev1-impl2@rigged-buildout
  dev1.qa: dev1-qa@rigged-buildout

Spec + bindings is the proven recovery pair for adopted rigs. Spec gives OpenRig the intended topology. Bindings tells OpenRig which discovered live session belongs in each logical node.

Proven adopted-rig recovery workflow

This workflow is proven for the case where the external tmux sessions are still alive:

rig release <rigId> --delete
rig discover --json
rig adopt <spec.yaml> --bindings-file <bindings.yaml>

What this does:

• removes OpenRig management without killing the sessions
• re-discovers those same sessions as unmanaged
• re-attaches them to the topology defined by the spec + bindings

Important limits:

• this is for sessions still alive
• spec alone is not enough for adopted rigs; you also need bindings
• this does not yet mean OpenRig can recreate dead external sessions from nothing

Add unmanaged pods into an existing rig

This is the proven workflow when a rig is already managed, but a new pod was created outside OpenRig and you want to add it later:

rig adopt <pod-fragment.yaml> --bindings-file <pod.bindings.yaml> --target-rig <rigId>

Use this when:

• the target rig already exists
• the new sessions are live and visible in rig discover --json
• you want additive topology growth, not a full rebuild

What to prepare:

• a pod fragment spec with only the new pod
• a bindings file mapping the new logical IDs to the live session names

Verification loop:

rig discover --json
rig adopt <fragment.yaml> --bindings-file <bindings.yaml> --target-rig <rigId>
rig ps --nodes --json
rig export <rigId> -o rig.yaml

Success looks like:

• the new sessions stop appearing in rig discover
• the new logical IDs appear in rig ps --nodes --json
• rig export includes the new pod

Mixed-origin rigs are allowed

One rig can contain both:

• adopted nodes bound from already-running sessions
• OpenRig-launched nodes created later with rig expand / rig launch

Current safety rule:

• rig release is for claimed/adopted-only rigs
• if a rig contains launched nodes, rig release fails with contains_launched_nodes

Manager-assisted recovery

The proven operator pattern is:

• keep one OpenRig manager session outside the rig it manages
• address the target by rig name, not cached rig ID
• resolve the current owner from fresh rig ps --nodes --json
• send the manager the spec path, bindings path, and verification steps with rig send

This lets ordinary agents ask the manager for OpenRig help instead of every agent needing to be an OpenRig expert.

Add/remove running topology parts

rig expand <rig-id> <pod-fragment-path> [--rig-root <path>] [--json]
rig launch <rigId> <nodeRef> [--json]
rig remove <rigId> <nodeRef> [--json]
rig shrink <rigId> <podRef> [--json]
rig unclaim <sessionRef> [--json]

Specs and Validation

Validate specs

rig spec validate <path> [--json]
rig spec preflight <path> [--rig-root <root>] [--json]
rig agent validate <path> [--json]

Spec library

rig specs ls [--kind <kind>] [--json]
rig specs show <name-or-id> [--json]
rig specs preview <name-or-id> [--json]
rig specs add <yaml-or-directory> [--json]
rig specs sync [--json]
rig specs remove <name-or-id> [--json]
rig specs rename <name-or-id> <new-name> [--json]

rig specs add <directory> installs a full spec tree when the directory contains rig.yaml or agent.yaml.

MCP

rig mcp serve [--port <port>]

Current shipped MCP tools:

• rig_up
• rig_down
• rig_ps
• rig_status
• rig_snapshot_create
• rig_snapshot_list
• rig_restore
• rig_discover
• rig_bind
• rig_bundle_inspect
• rig_agent_validate
• rig_rig_validate
• rig_rig_nodes
• rig_send
• rig_capture
• rig_chatroom_send
• rig_chatroom_watch

Troubleshooting and Weird States

When the CLI behaves strangely, use the smallest truthful check first:

rig whoami --json
rig daemon status
rig ps --nodes --json

Specific operator rules:

• Sent to ... + Verified: no is ambiguous delivery, not automatic failure. Check reply, rig capture, transcript evidence, or queue/outbox state before retrying.
• partial rig whoami --json can happen when identity is still inferable but the daemon-backed path is degraded.
• the unified-exec-process warning is a host/tooling-layer signal, not automatic proof that the OpenRig topology is unhealthy.

If you hit the unified-exec warning, inspect for stale one-shot helpers before touching live seats:

ps -axo pid,ppid,command | rg 'tmux send-keys|rig queue create|tmux attach|codex|claude'

Safe cleanup target:

• orphaned one-shot wrappers like tmux send-keys ...

Do not mass-kill:

• tmux attach ...
• codex ...
• claude ...

For deeper host/runtime triage, use the companion openrig-operator skill.

JSON and Error Posture

Design assumptions that hold in the shipped CLI:

• many operator commands support --json
• error messages are intended to say what happened, why it matters, and what to do next
• daemon-backed commands fail loudly when the daemon is stopped or unhealthy
• restore failure is not something you should silently reinterpret as success

After-Compaction Recovery Checklist

1. rig whoami --json
2. rig transcript <your-session> --tail 100
3. rig ps --nodes --json
4. rig chatroom history <rig> --limit 50

Commands That Do Not Exist

Do not assume these exist unless the shipped help starts listing them:

• rig claim
• rig blame
• rig replay

rig env IS shipped (was previously listed as not-present). It exposes status, logs, and down for service-backed rigs and managed apps; verify with rig env --help.