Getting started

Your path: Getting started → From your first pair to a team of your own.

OpenRig is a local control plane for Claude Code and Codex teams. It runs a daemon and a SQLite database on your machine, launches ordinary tmux-backed agent sessions, records their state, and gives you one CLI for booting, inspecting, and restoring the team.

Before you start

OpenRig runs on macOS or Linux and needs Node 22 or 24, tmux, and at least one coding harness installed and logged in. On Apple silicon, use Node 22. Native Windows is not yet supported; WSL2 is untested. The first-project starter uses your installed Codex executable and login; it does not need a Claude login. product-team and conveyor use both Claude Code and Codex, so both logins are needed for those. Check in the shell you will launch from:

node --version
tmux -V
codex --version
codex login status

Install and boot

# Install the CLI
npm install -g @openrig/cli

# Preview what setup will change, then apply it
rig setup --dry-run
rig setup

# Boot the smallest starter
rig up first-project

# Inspect the running team
rig status
rig ps --nodes
rig workspace doctor

# Open the terminal UI
rig tui

rig setup --dry-run shows the plan. rig setup applies it: it installs or checks both harnesses and cmux and reports what it changed. A missing Codex login is a real launch blocker for first-project; a missing Claude login is not. rig up first-project boots a one-pod, two-seat starter. rig status shows the daemon and rig status. rig ps --nodes lists every seat in the current rig with its state. rig workspace doctor runs the eight-check readiness diagnostic against the daemon's workspace. rig tui opens the terminal UI, where you will spend most of your time.

Pick a starter

Three starters cover most first runs. All ship in the library; rig specs ls lists the rest and rig specs preview <name> shows one before you boot it.

Starter	Shape	Seats	When to use it
first-project	1 pod	2 seats, both Codex: an owner and a checker	Your first run, or a single plan. The smallest useful team.
conveyor	4 pods: intake, plan, build, review	4 seats, 2 Claude and 2 Codex	A visible handoff path from intake to review. The light option with two Claude seats.
product-team	3 pods: orchestration, development, review	7 seats, 4 Claude and 3 Codex: an orchestrator pair, an implementer, QA, a designer, two reviewers	The full product team. Four Claude seats at once, so single-plan users should expect provider throttling.

rig specs preview conveyor
rig up conveyor

Stop it and bring it back

rig ps
rig down first-project --snapshot
rig up first-project

rig ps is the fleet glance: which rigs exist and their status. rig down <name> --snapshot stops the rig, attempting a snapshot first. A snapshot failure is reported and does not stop the teardown. rig up <name> brings it back by name and reports each seat's outcome: resumed or rebuilt, started fresh, waiting on a decision or attention, or failed.

Two users, always together

The human. Directs the work. Decides what to build, which team to boot, when to snapshot. Watches the terminal UI. Steps in when something needs a judgment call.

The coding agent. Drives the CLI. Runs rig up, rig ps, rig restore. Reads error messages, adapts, retries. The CLI is designed for this user, with --json on most commands.

The relationship: the human directs the agent; the agent drives the CLI. The system is honest to both: the agent needs accurate error messages, the human needs an accurate view of the team.

Core concepts

Term	What it is	Reference
Seat	A named position in a rig with a role and an address. A session occupies it; when the session ends, the seat keeps its name, role and accumulated context.	/specs/taxonomy
Pod	A bounded context group inside a rig. Holds seats whose knowledge is useful to each other, pod-local edges, and an optional continuity policy.	/specs/taxonomy
Rig	A team assembled for a purpose: pods, seats and the edges between them, described in one file and run as one unit.	/specs/taxonomy
RigSpec	The declarative file, rig.yaml, that describes a rig's pods, members, edges, continuity and startup. A member in the file is a seat when it runs.	/specs/rigspec
AgentSpec	A portable single-agent blueprint, agent.yaml: resources, profiles, startup, lifecycle.	/specs/agentspec
RigBundle	A portable archive of a RigSpec plus its vendored AgentSpecs, with integrity verification, for moving a rig between machines.	/specs/rigbundle

What ships in the library

The spec library is part of the product, not a folder on disk. rig specs ls shows what ships, rig specs preview shows a rig before you launch it, and rig up <name> boots from a proven example instead of starting every rig from scratch. That makes the library useful for reuse as much as onboarding: point an agent at it and tell it to start from an existing pattern.

Product vocabulary

A handful of words name the things you work with day to day. The first group is the topology, what a rig is made of. The second is the coordination layer, how a team passes work around without losing it. Both are first-class product surfaces; the taxonomy page defines the full set.

Topology

• fleet: every rig on a machine, or across machines
• rig: a team assembled for a purpose
• pod: a bounded context group inside a rig
• seat: a named position in a pod, with a role and an address
• session: the Claude Code or Codex process occupying a seat right now
• snapshot: a point-in-time restore point for a rig
• up / down: boot a rig by name, or stop it (--snapshot asks for a restore point first; the attempt can fail without stopping the teardown)

Coordination

• queue item: one unit of owned work, with a state and a history
• handoff: passing work to another seat, transactionally
• workflow: a declared sequence of work the daemon runs step by step
• chatroom: durable rig-scoped messaging, stored in the database
• context pack: addressed context that primes a seat
• watchdog: a scheduler whose jobs survive daemon restarts

Where to go next

• From your first pair to a team of your own: launch two agents, make one reviewed change, then grow the team around your work.
• The terminal UI: what you see after rig tui, and how to move around it
• Messaging: how seats reach each other
• Coordination: work that keeps its owner
• Continuity and Lifecycle: stopping, restoring, growing
• CLI reference: every command

---

Next: Run OpenRig across machines to keep work with an always-on home team while your laptop comes and goes.

Read as Markdown