OpenRig

A harness wraps a model. A rig wraps your harnesses. Define your agent team in YAML, boot it with one command. Claude Code and Codex in the same rig, managed as one system.

OpenRig turns AI coding agents from a pile of terminal sessions into a persistent, organized team. Talk to a lead agent about the outcome you want; it can coordinate specialists across teams and bring you results and decisions that need your attention. Start with a repository and one useful change, then keep the team's work and context at the same addresses.

See it running

Start here: the guided first-use path: install, launch a two-agent team in your repository, and get one reviewed change.

Install and first run

Requires Node.js 22 or 24 and tmux, on macOS or Linux. On a Mac with Apple silicon, use Node.js 22. Native Windows is not supported yet, and WSL2 has not been tested. Launching a rig writes provider hooks and workspace trust settings. Before running the commands below, read what OpenRig changes on your machine and back up the relevant files.

npm install -g @openrig/cli
rig setup --dry-run

To install with Bun instead, run bun add -g @openrig/cli. OpenRig still runs on Node.js, so install Node.js 22 as well. Bun may block this package's postinstall script, in which case the Node.js and SQLite check described under what OpenRig changes on your machine does not run at install time.

Review setup's plan before applying rig setup: it checks both native harnesses and cmux. This starter requires tmux and authenticated Codex; the other harness and terminal provider are optional for its repository task.

Before launching, ask your agent to configure your chosen permissions: keep prompts, remember selected commands, or deliberately choose broader access. The agent handles setup and verification; OpenRig's shipped defaults stay unchanged.

Check prerequisites in your launch shell:

tmux -V
codex --version
codex login status

Resolve missing tools or login before continuing. From your repository, inspect the plan before launching the two Codex seats, an owner and a checker:

cd /path/to/your/repository
rig up first-project --cwd . --plan
rig up first-project --cwd .
rig tui --shared

The kernel provides separate operational support and the shared dashboard. To detach without stopping the dashboard, press Ctrl-b then d; rig tui --shared returns to that view. Plain rig tui opens an independent view. Closing a viewing terminal does not mean you should relaunch the team.

Check project-seat readiness with rig ps --nodes --rig first-project and resolve any authentication, trust or permission prompt before assigning work. Then give the owner one bounded outcome from your repository:

rig send dev-owner@first-project 'Implement <one useful change>. Track the task in the queue and return its ID. Keep it local, verify the behavior, ask dev-check@first-project to check the exact candidate, and record the result and how I can try it.'
rig queue list --destination dev-owner@first-project --limit 1000

Sending a message does not itself create a queue item; the owner records the task. Read the final artifact and the review of its exact candidate, then return to the same owner for the next change.

Community

• Questions: Discussions › Q&A
• Bugs and feature requests: open an issue
• Contributing: CONTRIBUTING.md · Code of Conduct · Security policy · Getting help
• Videos: youtube.com/@openrig
• Releases: GitHub Releases and npm @openrig/cli

We aim to acknowledge issues and pull requests within one day; see CONTRIBUTING.md for review targets.

What OpenRig changes on your machine

OpenRig writes instance state, provider integration and workspace files as part of setup and operation. These include trust settings and executable hooks. The summary below follows this source revision; check rig --version when using a published package, since repository guidance can be ahead of npm.

What It Does

OpenRig is a multi-agent harness — it manages the system that coding agents form when you run them together. Not the agents themselves, but the team they create: which sessions are running, how they relate, how to recover after a reboot, and how to stop it from becoming terminal sprawl.

• Define topologies in YAML (RigSpec) with pods, edges, and continuity policies
• Boot everything with rig up — tmux sessions, harnesses, startup files, readiness checks
• See rigs, pods, and seats in the TUI topology table and graph; inspect projects, specs, feeds, and instance health
• Discover existing Claude Code and Codex sessions in tmux and adopt them into a managed rig
• Snapshot the topology with rig down --snapshot, restore by name with rig up <name>
• Communicate across agents with rig send, rig broadcast, and rig chatroom
• Protect a seat where you type by hand holds automatic messages and wakes instead of typing them into that seat
• Connect Slack through an app you create in your own workspace
• Evolve running topologies with rig grow, rig shrink, rig launch, rig remove

Starter Rigs

Use first-project for the focused first-use path. product-team is an optional larger product-development example:

rig specs preview product-team --kind rig
rig up product-team

For a smaller starter, use conveyor:

rig specs preview conveyor --kind rig
rig up conveyor

How It Works

OpenRig is a local daemon + CLI + terminal UI + MCP server, built on tmux.

CLI / TUI / MCP
      |
Hono HTTP daemon
      |
  Domain services
      |
  SQLite + tmux + runtime adapters

Terminal UI and Workspaces

The TUI shows the team's coordination state; herdr and cmux show the actual agent terminals alongside it. With herdr installed and connected, open the starter's terminals together:

rig terminal open first-project --provider herdr

Key Concepts

• RigSpec: Declarative multi-agent harness definition in YAML.
• AgentSpec: Reusable agent blueprint with skills, guidance, hooks, profiles, and startup contracts.
• Seat: A stable role and address in a rig.
• Pod: A group of related seats with shared guidance and context.
• Discovery: rig discover fingerprints existing tmux sessions. rig adopt brings them under management.
• Snapshot/Restore: rig down --snapshot captures full state. rig up <name> restores from latest snapshot.
• RigBundle: Portable archive with vendored AgentSpecs and SHA-256 integrity.
• Culture: CULTURE.md sets coordination norms for the group.

Agent-Managed Software

A rig can package actual software alongside the agents that manage it. The shipped example is secrets-manager: a HashiCorp Vault instance operated by a specialist agent.

Requirements

• Node.js 22 or 24. Node 20 is no longer supported.
• tmux
• macOS or Linux.

Comparison with Claude Managed Agents

OpenRig is open source and self-hosted, with Claude Code and Codex in the same team. You operate it on your own infrastructure; the selected providers' model usage costs still apply.