OpenRig cheatsheet
Understand the team, choose a workflow and copy the commands you need.
Work through one lead
Give the lead a concrete outcome, constraints and a way to check success. It coordinates specialists and review; you follow the task and result.
- Rig & seat
- A rig is a persistent team. A seat is a role with an address such as
dev-build@starter. Its occupant or native conversation can change. - Context & skills
- Context explains the project and where existing systems live. A router helps find it; a skill gives the procedure for a specific situation.
- Spec & bundle
- A RigSpec is the YAML blueprint. A bundle packages the team and its declared resources so another machine can install them.
What changed in 0.7.2
Upgrade and account homes
Install 0.7.2, then restart the daemon: six database updates apply from 0.7.1. Core 0.1.19 replaces managed plugin and skill files after backing them up under $OPENRIG_HOME/backups/managed-refresh/. Reopen the TUI and terminal views. Set absolute CLAUDE_CONFIG_DIR or CODEX_HOME in rig/member env:; rig up --env ignores these two names.
Accounts, runtimes and permissions
provider switch now acts. Precheck first; Codex switching is Linux-only and affects peers sharing its home. Claude can use a per-seat token file or return with --stored-login. set-runtime starts a new native conversation with a handover and keeps the seat address and work claims. Claude members support claude_permissions or set-permissions --rules, effective next launch/resume. Allows do not narrow inherited grants; full_bypass denies are not guaranteed. Before downgrade, set equivalent native rules.
Restore and delivery
Codex restores retain commit and topology write access. In-place restart reads the running home and preserves roots containing spaces; ordinary resume/restore with spaces in workspace or queue-state paths remains limited. Inspect login_required, model_selection_gate, uncertain restarts and owed Claude restore stages. Native prompts still require a person. Codex mid-turn sends may redirect current work; use --wait-for-idle for separate work. Sends retained during a runtime switch need resending after cutover.
MCP and operational limits
MCP adds rig_queue_handoff and rig_queue_unclaim (36 tools). On Linux, the daemon runtime directory is inherited with DBUS_SESSION_BUS_ADDRESS=disabled:; declare a needed bus address in env:. Codex stdio MCP needs env_vars = ["XDG_RUNTIME_DIR"] in config.toml. Token usage refresh consumes a model turn; ordinary refresh reads daemon logins. Runtime/home native coverage is partial. Long-paste issue #14, restore approvals, macOS Claude attention and Slack replies without --reply-to remain caveats. A daemon restart does not reload surviving agent hooks.
Choose a command and keep agents oriented
| Need | Use | What it gives you |
|---|---|---|
| Talk to a live agent | rig send | Input to its terminal. Follow the reply; delivery is not completion. |
| Assign accountable work | rig queue create | A durable task ID, owner and history. Follow handoffs through review. |
| Find a past decision | rig ask | Retained transcript evidence. --wake executes an agent and uses quota. |
| Find project knowledge | rig context work-install, list, get | The selected work context or a library reference. Printing it does not deliver it to another seat. |
| Check what is happening | rig ps, capture, queue show | Live status, screen output and retained work. Check all three when a result is unclear. |
Give the agent a map before details
Keep AGENTS.md as an entry point to the project’s architecture, decisions, current work and router skills. Show what already exists before asking for implementation. Read the relevant sources once the agent knows where to look.
Keep knowledge addressable and checkable
Link to one maintained source instead of copying it into every note. A library address such as world-public/start-here.md#what-to-trust selects a Markdown section; local project files use the addressable-Markdown resolver. Treat logs and expert recollections as evidence to check. Age alone does not make a note authoritative.
Recover context without changing the outcome
After compaction or a handover, re-read the current task, its source documents and acceptance criteria. Use the refocusing procedure when the session has drifted. Keep a short example of the mistake and its consequences in the appropriate project or seat notes so the next occupant can learn from it.
Scale a useful team
Start with one lead and one reviewed result. Add specialists or registered hosts when the work needs them. Another host needs its own runtime logins and explicit routing; the same rig name on two machines does not identify the same team. A bundle carries declared files, while host settings and retained session history have their own lifecycle.
Based on Mike Schwarz’s OpenRig video. Explore the Workshop team and its install choices.
Customize examples my-project / dev-owner
Common workflows
Start with guided setup or choose the task you need. Customize names and paths above.
Command reference
Search or choose a category. Open Notes & source for conditions and details.
Version & sources
Commands checked against OpenRig 0.7.2 / 8b180689 source. Use rig <command> --help for your installed version. Provider integrations were not run.
Replace variables with values from CLI output: $RIG_ID is a rig ID; $SEAT_ID is a logical seat ID such as dev.owner; $QITEM_ID and $SNAPSHOT_ID identify saved records. Set $BUNDLE_SOURCE to a real bundle path or GitHub folder URL and $ACCOUNT_REF from provider status. Choose rig and seat names that match your team; model availability depends on the harness and account.