OpenRig: organize Claude Code and Codex into a recoverable team with YAML
A local tool that turns Claude Code and Codex terminals into a recoverable team instead of scattered tmux sessions.
GitHub mvschwarz/openrig Updated 2026-09-28 Branch main Stars 976 Forks 104
TypeScript Multi-agent orchestration Claude Code Codex tmux Node.js 20/22/24 SQLite MCP

🧭 Decision Guide

Why trending now: Cannot be determined from the provided material

Try it if you

  • You want Claude Code and Codex to split work in one repository, with an owner and checker seat handoff.
    The README section “Install and first run” shows the two-seat first-project flow with dev-owner@first-project and dev-check@first-project.
  • You need to define pods, edges, and continuity policies in YAML and restore the topology after a restart.
    The README section “What It Does” explicitly supports RigSpec YAML, rig down --snapshot, and restoration by name.
  • You want the TUI to show topology, projects, feeds, Specs, and instance health while retaining tmux terminal access.
    The README sections “What It Does” and “How It Works” describe the TUI topology table/graph and directly attachable tmux sessions.
  • You need agents to manage their own rig through MCP, including rig_up, rig_ps, and rig_send.
    The README section “How It Works” lists the MCP tools rig_up, rig_ps, rig_send, and rig_chatroom_send.

Skip it if you

  • Your environment cannot install Node.js 20, 22, or 24, or does not have tmux.
    The README section “Requirements” lists Node.js 20/22/24 and tmux as requirements.
  • You cannot accept rig setup modifying provider hooks or workspace trust settings.
    The README section “Install and first run” says launching a rig writes these settings and requires reading the machine-change section first.
  • You need a mature React Web UI rather than a TUI, CLI, or tmux workflow.
    The README section “How It Works” says the older React Web UI is in maintenance mode with best-effort support.
  • You do not want to operate infrastructure yourself and prefer a provider-managed agent team.
    The README section “Comparison with Claude Managed Agents” describes OpenRig as open source, self-hosted, and operated on your own infrastructure.

Requirements

  • Node.js 20, 22, or 24
  • tmux
  • starter requires tmux and authenticated Codex
  • Optional: herdr or cmux for terminal workspaces
  • Optional: Docker for service-backed rigs and managed apps
  • Launching a rig writes provider hooks and workspace trust settings

First step (verbatim from README)

npm install -g @openrig/cli

Watch out

  • When installing with Bun, the package postinstall script may be blocked.
    The README section “Install and first run” explicitly says Bun may block this package's postinstall script.
  • Already-adopted sessions may need a restart before loading newly written runtime config.
    The README section “Setup and Troubleshooting” says already-running adopted sessions may need restart.
  • Before rig setup, distinguish core setup from rig setup --full; the latter also attempts to install jq and gh.
    The README section “Setup and Troubleshooting” lists both setup paths and their differences.
  • Closing a viewing terminal does not stop the dashboard and should not trigger a team relaunch.
    The README section “Install and first run” says closing a viewing terminal does not mean relaunch the team.

Alternatives

  • Claude Managed Agents：It is a better fit when you do not want to run OpenRig on your own infrastructure or prefer a managed agent team.
    README section “Comparison with Claude Managed Agents”
  • Native tmux sessions：It is simpler when you only need to create and inspect terminal sessions without RigSpec, topology TUI, MCP, or rig send team-management capabilities.
    General domain knowledge

Not stated in the README

  • The README does not specify supported operating systems or platform differences.
  • The README does not provide maximum supported agent, pod, or seat counts.
  • The README does not provide performance, resource-usage, or concurrency limits for multi-agent operation.
  • The README does not specify a compatibility matrix for Claude Code, Codex, or OpenRig model versions.
  • The README does not specify the exact paths, contents, or rollback method for provider hooks and workspace trust settings.
  • The README does not provide actual usage-cost details for Claude Code, Codex, or OpenRig.
  • The README does not explain SQLite backup, migration, or concurrent-write behavior.
  • The README does not explain authentication, authorization, or sensitive-data protections for agent messaging.

💡 Deep Analysis

6
No My workstation already has Node.js 22 and tmux, but Codex authentication, workspace trust, and provider hooks may not be configured. Should I launch first-project immediately?
For: A local self-hosted user on Node.js 20, 22, or 24 who already has tmux but must verify Codex login and machine-configuration changes

No, not immediately, because the README requires reviewing machine changes and confirming that Codex is authenticated first.

  • The supported prerequisites are Node.js 20, 22, or 24 plus tmux; the starter additionally requires authenticated Codex.
  • rig setup --dry-run shows planned provider hooks, workspace trust settings, tmux defaults, and runtime resources, and the README says to review and back up relevant files first.
  • Before launch, verify tmux -V, codex --version, and codex login status; otherwise agents may stop at authentication, trust, or permission prompts.
  • rig doctor checks system health after setup. Existing adopted sessions may need a restart before they use newly written runtime configuration.
  • Install and first run: "Requires Node.js 20, 22 or 24 and tmux."
  • Install and first run: "This starter requires tmux and authenticated Codex"
  • Install and first run: "rig setup --dry-run"
  • Setup and Troubleshooting: "Already-running adopted sessions may need restart before they pick up newly written runtime config."
rig setup --dry-run
Not stated in the README：The README does not list the exact file paths for workspace trust or provider hooks on each operating system.；It does not state whether enterprise proxies, credential managers, or network policies can block setup.
No I am not comfortable with tmux or keyboard-driven TUIs and would prefer a remote web console to inspect Claude Code and Codex topology and tasks. Does OpenRig fit my working style?
For: A developer who prefers a graphical IDE or remote web console but still wants to inspect the state of a Claude Code and Codex team

No, because OpenRig’s primary interfaces are the CLI, TUI, MCP, and tmux, while the older React Web UI is only maintained on a best-effort basis.

  • The architecture explicitly lists a local daemon, CLI, terminal UI, and MCP server, with tmux hosting agent sessions.
  • The TUI provides topology tables and graphs, feeds, projects, terminals, and health information, but it remains a terminal interface rather than a remote Web console.
  • The README states that the older React web UI is in maintenance mode with best-effort support, so it should not be treated as the primary product entry point.
  • rig tui --shared provides a shared dashboard, but closing the viewing terminal does not stop the team; this workflow favors users comfortable with terminals.
  • How It Works: "The older React web UI remains in maintenance mode with best-effort support."
  • How It Works: "OpenRig is a local daemon + CLI + terminal UI + MCP server, built on tmux."
  • What It Does: "See rigs, pods, and seats in the TUI topology table and graph"
  • Install and first run: "rig tui --shared"
rig tui --shared
Not stated in the README：The README does not explain whether the daemon can be accessed securely over SSH, a reverse proxy, or a browser.；It does not specify which topology, task, or recovery operations are currently supported by the old Web UI.
It depends I currently want to manage Claude Code and Codex with SQLite on one machine, but I will later need multi-host, multi-user, highly available agent orchestration. Can OpenRig serve as the long-term production control plane?
For: A technical lead managing Claude Code, Codex, and tmux sessions through a single-machine SQLite control plane while planning to scale to highly available multi-host orchestration

It depends: it fits a single-machine, self-hosted control plane, but the README does not justify treating it as a multi-host highly available platform.

  • The architecture uses a local daemon, SQLite, and tmux, while the Requirements section centers on local Node.js and tmux.
  • The README emphasizes self-hosting, operating on your own infrastructure, and local sessions, topology, snapshots, and recovery, which fits workstation use.
  • Docker is listed as optional for service-backed rigs and managed apps; that does not imply that the daemon, SQLite, or tmux provide cluster coordination.
  • The project insight explicitly characterizes SQLite and the local daemon as suitable for single-machine or single-user control planes, not multi-host clusters or high availability.
  • How It Works: "OpenRig is a local daemon + CLI + terminal UI + MCP server, built on tmux."
  • How It Works: "SQLite + tmux + runtime adapters"
  • Requirements: "Docker for service-backed rigs and managed apps"
  • Project insight: "SQLite and the local daemon are suitable for single-machine or single-user control planes"
rig doctor
Not stated in the README：The README does not describe multi-host node discovery, SQLite replication, failover, or multi-user isolation.；It does not state whether the daemon supports remote deployment, TLS, horizontal scaling, or external databases.
Yes I already use Claude Code and Codex in a local repository, but I now have to maintain several separate terminal sessions. Can I use OpenRig to organize one owner and one checker into an inspectable and recoverable team?
For: A developer who needs to run Claude Code and Codex together in a local repository, with both agents managed through tmux seats

Yes, because OpenRig is specifically designed to turn separate Claude Code and Codex terminal sessions into one managed rig.

  • The first-run workflow explicitly creates two Codex seats: an owner and a checker, then assigns one bounded repository task with rig send.
  • Every agent runs in its own tmux session, so it can be attached to and inspected independently of the viewing terminal.
  • rig ps --nodes, the TUI, queues, and messaging commands expose readiness, topology, and task records.
  • rig down --snapshot and named restore preserve topology and coordination context, but they are not a complete backup of code, credentials, or external services.
  • Install and first run: "inspect the plan before launching the two Codex seats, an owner and a checker"
  • Install and first run: "rig ps --nodes --rig first-project"
  • What It Does: "Every agent runs in a tmux session you can attach to, inspect, and work with directly."
  • What It Does: "Snapshot the topology with rig down --snapshot, restore by name with rig up"
rig setup --dry-run
Not stated in the README：The README does not specify the maximum number of seats that one rig can run reliably.；It does not detail how much agent context a snapshot restores or how uncommitted code behaves after recovery.
Yes I want to assign implementation and review to an owner and a checker, requiring the checker to review the exact candidate change and record tests and conclusions. Can OpenRig support this handoff workflow?
For: A small-team engineering lead using first-project or adversarial-review workflows who requires an owner to deliver an exact candidate for independent checker review

Yes, because the README’s first-project workflow already connects an owner, a checker, a task queue, and review of an exact candidate.

  • The rig send example asks the owner to implement one concrete change, record a task ID in the queue, verify behavior, and ask dev-check to check the exact candidate.
  • rig queue list can inspect tasks by destination; the README explicitly says that sending a message does not itself create a queue item.
  • OpenRig provides rig send, rig broadcast, and rig chatroom for handoff communication, but code correctness still depends on the agents and human review of the final artifact.
  • Starter rigs include first-project, conveyor, implementation-pair, and adversarial-review templates; the README does not guarantee that each template fits every repository structure.
  • Install and first run: "Keep it local, verify the behavior, ask dev-check@first-project to check the exact candidate"
  • Install and first run: "Sending a message does not itself create a queue item; the owner records the task."
  • What It Does: "Communicate across agents with rig send, rig broadcast, and rig chatroom"
  • Project insight: starter rigs include first-project, conveyor, implementation-pair, and adversarial-review
rig up first-project --cwd . --plan
Not stated in the README：The README does not state whether queues support dependencies, deadlines, or cross-rig queries.；It does not define how a checker marks failure, blocks the owner, or automatically triggers rework.
Yes I build local agent workflows in TypeScript and want Claude Code or Codex to invoke rig_up, rig_ps, and rig_send through MCP while I inspect topology in the TUI. Does OpenRig fit this control-plane constraint?
For: A TypeScript AI-engineering experimenter who wants agents to manage topology while humans observe state through the CLI or TUI

Yes, because OpenRig routes the CLI, TUI, and MCP through the same local daemon instead of maintaining separate state for agents and humans.

  • The architecture is CLI / TUI / MCP → Hono HTTP daemon → domain services → SQLite, tmux, and runtime adapters.
  • MCP exposes tools such as rig_up, rig_ps, rig_send, and rig_chatroom_send, allowing agents to participate in topology and communication management.
  • The TUI exposes rigs, pods, seats, specs, feeds, projects, terminals, and instance health.
  • The project is primarily TypeScript, but the README does not promise that MCP tools can be embedded directly into any TypeScript application; it describes MCP access for agent runtimes.
  • How It Works: "OpenRig is a local daemon + CLI + terminal UI + MCP server"
  • How It Works: "MCP: Tools so agents can manage their own topology (`rig_up`, `rig_ps`, `rig_send`, `rig_chatroom_send`, etc.)"
  • How It Works: "CLI / TUI / MCP → Hono HTTP daemon → Domain services → SQLite + tmux + runtime adapters"
  • Project data: the main language is TypeScript
rig doctor
Not stated in the README：The README does not specify MCP transport configuration, authentication, or default ports.；It does not describe concurrency handling when multiple agents modify topology at the same time.

✨ Highlights

  • YAML RigSpec defines pods, edges, and continuity policies
  • rig up starts tmux, harnesses, and readiness checks
  • The TUI shows rigs, pods, seats, and instance health
  • Discovers and adopts Claude Code and Codex tmux sessions
  • Installation requires Node.js 20/22/24, tmux, and Codex login

🔧 Engineering

  • Describe multi-agent topologies, pods, edges, and recovery policies with RigSpec YAML.
  • Use rig send, rig broadcast, and rig chatroom to communicate between Claude Code and Codex.
  • Save a topology with rig down --snapshot and restore it by name with rig up.
  • CLI, TUI, MCP, and SQLite/tmux jointly manage team state and terminal sessions.

⚠️ Risks

  • rig setup writes provider hooks and workspace trust settings, so changes must be reviewed first.
  • The starter requires tmux and authenticated Codex; missing login blocks the launch flow.
  • Bun may block postinstall, so the Node.js and SQLite checks may not run at install time.
  • The older React Web UI is in maintenance mode with best-effort support only.

👥 For who?

  • Development teams that need to coordinate Claude Code and Codex locally in tmux.
  • Engineers who want YAML-managed multi-seat topologies, handoffs, reviews, and recovery.
  • Users able to maintain Node.js 20/22/24, SQLite, tmux, and local runtimes.