OpenRig: run Claude Code and Codex as one persistent agent team

Why this is blowing up now

The agent harness is having its moment. Claude Code, Codex, and the rest are genuinely useful, but running them still feels like managing a group chat where everyone forgets the thread: one terminal per agent, context evaporating between sessions, and nobody in charge. This morning GitHub's trending page is dominated by attempts to fix that — and sitting at #3 is OpenRig, the project whose entire pitch fits in one line of its README: "A harness wraps a model. A rig wraps your harnesses."

At the time of writing, OpenRig has 3,366 stars and 228 forks, 37 releases, and about 3,155 commits — it's the open-source system behind its author's "AI civilization" experiments, and it's built for exactly one job: letting you define a whole team of agents (an owner who implements, a checker who reviews, a whole product pod if you want) in a single rig.yaml, then launching it as persistent seats that keep working, keep their context, and answer to addresses like dev-owner@first-project. Under the hood those seats are tmux sessions; on top of them OpenRig puts a daemon, a shared dashboard, a work queue, and a kernel that searches the team's memory on disk. This is a team harness, not another agent — and it's different enough to be worth doing by hand rather than reading the README.

What you'll need

• Node.js 22 or 24 — a hard requirement from the package. I ran this tutorial on v24.20.0; check yours with node --version.
• tmux — OpenRig's seats live in tmux sessions. I had 3.4 installed; rig doctor (below) verifies it for you.
• macOS or Linux. The README is explicit: no native Windows support, WSL2 untested. I worked on Linux.
• A Claude Code or Codex account — your existing login, nothing new to buy. Steps 1–4 and 6 are fully verifiable without one; the actual agent launch in step 6's second half needs claude auth login or codex login to have run once. I mark that boundary clearly when we get there.
• About fifteen minutes.

Step 1 — Install the CLI

OpenRig ships as a single npm package. Install it globally:

npm install -g @openrig/cli
rig --version

I got 0.6.3 (8b5e9488) — the current release. (There's a Bun path too — bun add -g @openrig/cli — but the README notes you still need Node 22+ underneath.) The install is quick; the daemon and its bundled UI come inside the package, so there's no second thing to chase.

Step 2 — Read the setup plan before it touches anything

Most tutorials would tell you to run rig setup blind. OpenRig gives you a better option: --dry-run prints every mutation it would make. Run it first:

rig setup --dry-run

On my box it reported: profile core, platform linux, Node 22/24 and tmux checks, then a series of [SKIP] lines for steps it won't perform in a dry run — installing brew, tmux, cmux, the Claude and Codex CLIs, writing the tmux config block, and finally a verify pass. The useful part is what it tells you it would do on a real run: append an idempotent OpenRig block to ~/.tmux.conf, create the ~/.openrig daemon state directory, write workspace trust entries into your provider configs (~/.claude.json, .claude/settings.local.json, ~/.codex/config.toml with trust_level="trusted" for Codex), and seed an openrig-skills directory into ~/.claude/skills and ~/.agents/skills. It also asks one interactive question — the guided permission policy: "Allow your agents to run OpenRig commands without repeated permission prompts?" (Yes is recommended; No keeps the prompts. Either way, the docs stress this is not global YOLO mode — rig up always works without a policy.)

My advice before the real rig setup: back up ~/.tmux.conf and your provider configs. The changes are sane and documented, but they're yours to own.

Step 3 — Start the daemon and check system health

OpenRig is client/daemon: the CLI talks to a local daemon that owns the teams. Start it:

rig daemon start
rig status

The daemon answered Daemon started on port 7433, and rig status gave me the layered health picture that makes the architecture legible:

Daemon running on port 7433
Kernel: auth_blocked (boots on daemon-start; distinct from daemon health)
Workspace root: ~/.openrig/workspace (default)
No rigs
cmux: unavailable

Note the honesty of that output: the daemon is fine, but the kernel — the subsystem that searches and reasons over everything on disk — boots separately and sits at auth_blocked because no provider is logged in. Daemon health and kernel readiness are distinct states, and OpenRig shows you both instead of papering over the difference. (I ran my whole test session against an isolated state directory so nothing here touched my real configs — the same OPENRIG_HOME trick works if you want a scratch playground.)

Now run the doctor:

rig doctor

  [OK] daemon_dist: Daemon dist found
  [OK] ui_dist: UI dist found.
  [OK] node_version: Node v24.20.0
  [OK] tmux: tmux 3.4
  [WARN] cmux_shell: cmux not found.
       Why: OpenRig can run without cmux, but Open CMUX actions and
       surface control will be unavailable.
  [OK] writable_home: Writable state paths verified.
  [OK] port: Port 127.0.0.1:7433 in use by OpenRig daemon.

System checks look good.

The single [WARN] is cmux — the open-source terminal multiplexer OpenRig can use for surface control. It's optional; OpenRig works fine on plain tmux, so you can ignore it unless you want the Herdr/cmux integration the docs describe.

Step 4 — Pick your starter team

OpenRig ships 13 built-in team specs. List them:

rig specs ls --kind rig

Alongside curiosities like adversarial-review, pm-team, and factory-rsi sit three getting-started teams. The official guide offers this chooser table:

Preview the one you want before launching anything. I picked first-project for this tutorial:

rig specs preview "first-project" --kind rig

first-project (rig, pod_aware) — Launch your first project in your
  repository: Codex implements, Codex reviews. Owner records and
  delegates your tasks.
Pod: dev (2 members)
  Seats: owner — codex; check — codex
  Agents: owner → local:../../../agents/development/implementer,
          check → local:../../../agents/development/qa

Two seats, two roles: an owner who implements and a check who reviews — the cheapest possible org chart that still gives you independent review. Now look at the actual definition file, because this is the whole mental model in one artifact:

version: "0.2"
name: first-project
summary: >
  Launch your first project in your repository: Codex implements, Codex reviews.
  Owner records and delegates your tasks.
agents:
  default:
    runtime: codex
    model: gpt-6-astra
pods:
  - id: dev
    members:
      - id: owner
        agent_ref: "local:../../../agents/development/implementer"
        culture_file: CULTURE.md
      - id: check
        agent_ref: "local:../../../agents/development/qa"
        culture_file: CULTURE.md
edges:
  - from: owner
    to: check
    kind: delegates_to

Read it top to bottom: the default agent runs on Codex, the dev pod has two seats, each seat points at an agent definition file (local: refs resolve relative to the spec file), each gets a CULTURE.md with the team's working agreements, and the edges declare that owner delegates to check. Teams as data, not as folklore in your shell history.

Step 5 — Log your provider in (the reader step)

Here is the one boundary of my sandbox. The official getting-started guide gives the exact pre-flight check:

claude --version && claude auth status
codex --version && codex login status

On my test box, codex --version reported codex-cli 0.149.0 — installed — but codex login status answered Not logged in. That is exactly why my kernel sat at auth_blocked in step 3, and it is why I could not spawn live agents: a real launch burns your own provider usage, and I am not spending yours from a sandbox. On your machine, run claude auth login or codex login once and these checks pass. Reuse the account you already pay for — OpenRig needs no subscription of its own.

Step 6 — Plan the launch, then launch

Even without a provider login you can rehearse the launch. --plan resolves the spec and runs preflight without spawning anything:

rig up "first-project" --cwd /tmp/rigtest-repo --plan

  resolve_spec: ok
  preflight: ok
Status: planned
  warning: dev.owner: permission_policy absent; launch_posture=floor
  warning: dev.check: permission_policy absent; launch_posture=floor

resolve_spec: ok, preflight: ok, Status: planned — the spec parses, the topology is legal, and the only warnings are the optional permission policy (remember: rig up always works without one; absence just means agents get prompted more). With a provider login, preflight would also confirm kernel auth instead of staying blocked.

Now the actual launch — this is your step, run from your own repository with your own login in place. Drop the --plan:

rig up "first-project" --cwd .

The daemon spawns the two seats as persistent tmux sessions in your repo. Verify with the readiness check straight from the official guide — no auth, trust, or permission prompts outstanding before you assign work:

rig status
rig ps --nodes --rig "first-project"

To watch the team the way mission control would, open the shared dashboard:

rig tui --shared

This attaches a shared tmux session — everyone (and every agent) sees the same screen. Detach without killing anything with Ctrl-b then d. The seats keep running; that's the whole point of persistent teams.

Step 7 — Give the team work

You don't DM the seats individually. You send work to an address — seat@rig — and the owner records it as a real task in the queue. The exact command from the official guide:

rig send "dev-owner@first-project" \
  'Add request logging to the API server. Write tests first, then implement.'

What happens next is the owner/checker loop this whole tutorial has been building toward: the owner records the task, asks dev-check to review the exact candidate, and the review lands in your queue. Inspect it any time:

rig queue list --destination "dev-owner@first-project" --limit 1000

One subtlety worth knowing, straight from the docs: sending a message is not the same as creating a queue item. The message is delivery; the owner records the task — that's what makes the work owned rather than just shouted into a terminal. For exact delivery semantics (--verify, --force, --wait-for-idle), rig send --help documents every flag.

Step 8 — Define your own team in YAML

Starter specs get you going; your own rig.yaml is the destination. This step is fully verified — I built a renamed team (my-team) and ran the complete validation path. There is one layout rule the docs underplay: local: agent refs resolve relative to the spec file, and the bundled agents themselves import local:../../shared — so your spec needs the library's directory shape around it. Mirror it:

my-team/
└── specs/
    ├── agents/          # copy of the bundled agents tree
    │   ├── development/
    │   │   ├── implementer/
    │   │   └── qa/
    │   └── shared/
    └── rigs/
        └── launch/
            └── my-team/
                ├── rig.yaml
                └── CULTURE.md

Edit the copy of rig.yaml — rename it, tweak the seats, change runtimes per seat — then validate and plan:

rig spec validate my-team/specs/rigs/launch/my-team/rig.yaml
rig up my-team/specs/rigs/launch/my-team/rig.yaml --cwd . --plan

Rig spec valid: my-team
  resolve_spec: ok
  preflight: ok
Status: planned

That round trip — validate, plan, then launch — is the whole OpenRig workflow in miniature. I confirmed two failure modes so you don't have to: copy the rig.yaml somewhere without the agents tree and validate passes but up --plan fails with agent_ref resolution failed; use an absolute local: path and validate rejects it outright ("local: ref must be a relative path"). Relative paths, library layout, validate-then-plan. Done.

When to use this vs the alternatives

OpenRig sits in a crowded corner of the tooling landscape. Here's how it actually differs from the things you might already use:

• Plain tmux + two terminals: the zero-dependency version of this workflow. What you don't get: defined roles, a work queue, shared context that survives sessions, or delegation edges. OpenRig is the team layer on top of tmux, not a replacement for it — the seats are tmux sessions.
• Herdr (the 41K-star Rust terminal multiplexer): Herdr gives you one terminal for all your agents; OpenRig gives your agents an org chart — roles, review loops, owned work. They're complementary, not rivals: the getting-started guide has an explicit Herdr integration (rig terminal open "$starter" --provider herdr), and we published a hands-on Herdr tutorial today if you want both.
• Orca (parallel agents in git worktrees): Orca parallelizes isolated tasks across worktrees; OpenRig persists a team with shared context and review loops in one repo. Parallelism vs. persistence — different axes, pick by the shape of your work.
• Raw Claude Code subagents: live and die inside one session. OpenRig seats are addressable (dev-owner@first-project), persistent, and keep their culture and context between your visits.
• Always-on personal agents (OpenClaw and kin): built for one agent doing your bidding around the clock. OpenRig is built for a team doing repo work with internal review. If your bottleneck is "I need a second pair of eyes on every change," that's the owner/checker pair.

Reach for OpenRig when the unit of work is a team outcome — a feature implemented and reviewed, a research task owned end to end — rather than a single prompt answered well.

The takeaway

Three things to carry out of this tutorial. First, the one-liner is the architecture: a harness wraps a model; a rig wraps your harnesses — OpenRig never tries to be the agent, only the team around it. Second, the workflow is validate → plan → launch: rig spec validate and rig up --plan cost nothing and catch every layout mistake before a single agent spawns. Third, auth_blocked is information, not breakage — the daemon, the kernel, and your provider login are three separate readiness states, and OpenRig shows you each one instead of failing mysteriously.

I installed 0.6.3, dry-ran the setup, started the daemon, doctored the system, previewed and planned the starter team, and validated a custom team spec — all from commands that ran exactly as shown. The last mile — claude auth login or codex login, then a real rig up — is yours, on your account, in your repo. When your checker reviews your owner's first pull request while you watch from the shared dashboard, you'll know the rig is working.

Related articles