OpenRig: Turn Claude Code and Codex into a YAML-Defined Agent Team

Who It's For

OpenRig is for developers who want to organize multiple coding agents into a fixed team: a rig wraps your harnesses, you define the agent team in YAML, and boot it with one command. Its most distinctive capability is running Claude Code and Codex side by side in the same rig, managed as one system. The value lies in the "team": instead of tending to each agent in separate terminal windows, write the members into one YAML file and let a single command plus unified readiness checks manage them.

Before starting, verify your environment and proceed only when all four items hold: Node.js 22 or 24 (22 on Apple silicon), tmux, macOS or Linux (Windows via WSL2), and a signed-in Claude Code or Codex. Close any gap first — that alone spares you most of the errors later. If you only use other agents, stay on native Windows, or run a different Node version, the official stance on support is unstated; treat it as unconfirmed.

Conversely, three situations call for holding off: users who only work in a graphical interface and don't want to write configuration; users who need to run directly on native Windows (not WSL2); and users who want clients other than Claude Code and Codex — official documentation doesn't cover these uses. In other words, if you normally run a single client and have no need for unified booting, the rig team structure brings limited benefit.

Your First Try in 3 Minutes

There is exactly one recommended main path: install the rigs skill into Claude Code with the official command, assuming the environment from the previous section is ready. Run this in a terminal:

npx skills add https://github.com/mvschwarz/openrig/tree/v0.7.0/skills/rigs --skill rigs --agent claude-code

The v0.7.0 in the command is the fixed version path given on the official page — copy it as is. Once installed, write your agent team definition in YAML; the order is: install the skill, write the YAML, initialize as needed (rig setup), then boot (rig up). Officially, it only says the team is defined in YAML and booted with one command — no fields, examples, or file locations are provided. For configuration details, defer to the skill's own instructions after installation and don't write config by guesswork.

Next comes initialization. Before running rig setup, know its side effects: it appends an OpenRig block to ~/.tmux.conf; on macOS it can install tmux via Homebrew; and unless you pass --no-herdr, it also installs Herdr. That is the checkpoint before executing — if you don't want Herdr, run it with --no-herdr.

Finally, boot: run rig up to bring up the tmux sessions, each harness and the startup files, and to run readiness checks. The success signals you can observe: the sessions for your team appear in tmux, each harness starts, and readiness checks report results item by item. If tmux shows no sessions or a readiness check reports an error, go back to the environment checklist and verify your Node version and tmux. Officially, nothing says whether rig up modifies files or accesses the network — unconfirmed. At this point no member has done any real work yet; confirm the boot is healthy before handing over real tasks.

Use Cases

Case 1: Claude Code and Codex collaborating on the same team. Scenario: you use both clients and want them inside one managed system. How: after installing the rigs skill, define both harnesses in the team YAML, then run rig up. Expected result: both boot as one system, their sessions appear in tmux, readiness checks report item by item, and both members stay visible in tmux, which makes comparison easy.

Case 2: Collapsing daily startup prep into one command. Scenario: you don't want to open tmux manually and bring up the members one by one every day. How: once the team YAML is in place, run rig up at the start of each day and let it handle tmux sessions, harnesses, startup files, and readiness checks. Expected result: the repetitive prep shrinks to one command, and the readiness results tell you directly whether the team is ready.

The two cases chain well: first confirm with Case 1 that the formation itself works, then turn it into a fixed daily entry point like Case 2. Both cases stop where official documentation stops: how members divide work after starting and which tasks they execute — there are no official examples, and nothing is invented here.

Boundaries

• Environment and clients: officially listed are only Node.js 22 or 24 (22 on Apple silicon), tmux, macOS/Linux (WSL2), and a signed-in Claude Code or Codex; other clients, native Windows, and other Node versions are all unconfirmed.
• Install surface and version: installation happens via npx skills add, and the official command is explicitly bound to --agent claude-code; no plugin marketplace or equivalent path for other clients is documented, so don't extrapolate on your own. The install path is pinned to v0.7.0, and no upgrade procedure is described.
• Side effects and checkpoint: rig setup appends an OpenRig block to ~/.tmux.conf, may install tmux via Homebrew, and installs Herdr unless you pass --no-herdr; confirm you accept these changes before running.
• Team definition: the specific YAML fields, examples, and file locations are not in official documentation; don't write configuration by guesswork.
• Readiness checks: run by rig up, but what exactly is checked and what happens on failure are unstated; treat the command output as the source of truth and don't assume automatic retries or rollback.
• Task behavior: OpenRig does team orchestration; official documentation doesn't cover rewriting text or modifying user files. Member agents' file, command, and network behavior at runtime depend on the client you choose; this article draws no additional security conclusions.
• Unconfirmed items: licensing and pricing, uninstallation, rig up's exit and cleanup behavior, and the member-count limit per rig — none of these were found in official documentation.