# Getting started

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 needs **Node 20 or newer**, **tmux**, and at least one coding harness installed and logged in. 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

- [The terminal UI](/docs/tui): what you see after `rig tui`, and how to move around it
- [Messaging](/docs/messaging): how seats reach each other
- [Coordination](/docs/coordination): work that keeps its owner
- [Continuity](/docs/continuity) and [Lifecycle](/docs/lifecycle): stopping, restoring, growing
- [CLI reference](/docs/cli): every command

---