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. Start with a repository and one useful change, then keep the team's work and context at the same addresses.

The terminal UI is the shared dashboard; the CLI drives work and coordination. The older web UI is in maintenance mode with best-effort support.

npm install -g @openrig/cli
rig setup --dry-run
cd <your-repository>
rig up first-project --cwd .
rig tui --shared

first-project has two native Codex seats: an owner and a checker. The kernel provides separate operational support and a shared TUI terminal. Check codex login status and inspect rig up first-project --cwd . --plan before launching. The guided first-use path covers readiness, a useful task, a reviewed result, Herdr/cmux terminals and recovery. 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.

First Run

Check readiness, then give the owner a bounded outcome from your repository:

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

Read the final artifact and the review of its exact candidate. Return to the same owner for the next change. To leave the shared dashboard without stopping it, 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.

Upgrading an existing instance to 0.5.9

0.5.9 makes $OPENRIG_HOME/context the addressable context library, writes Claude telemetry to state/context-usage (and provider telemetry to state/provider-usage), and installs the default System World at context/system/system-world.yaml. Existing instances cross this boundary by an Agent-Operated Migration from the shipped openrig-upgrade skill. The target runtime reads canonical-first with legacy-fallback while new writes use the canonical roots; a custom context-library root stays stable during activation. This is not a directory rename to do while an old collector writes.

# SKILL_DIR is the installed openrig-upgrade skill directory.
node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --help
node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --home "$OPENRIG_HOME"
node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --home "$OPENRIG_HOME" --apply-state --preimage /safe/path/layout-0.5.9-before

# Activate the exact target runtime separately. After every bounded legacy tail is followed by newer paired samples at both new state roots:
node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --home "$OPENRIG_HOME" --verify --preimage /safe/path/layout-0.5.9-before > /safe/path/layout-0.5.9-verify.json

# Run the separately invoked non-destructive finalizer only with that exact receipt:
node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --home "$OPENRIG_HOME" --apply-library --preimage /safe/path/layout-0.5.9-before --verification /safe/path/layout-0.5.9-verify.json

# Restore only helper-owned preparation/finalizer effects if the observed upgrade must be reversed:
node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --home "$OPENRIG_HOME" --rollback /safe/path/layout-0.5.9-before

--help prints the phase grammar without inventorying the instance. No phase flag intentionally runs the read-only plan; unknown options fail nonzero before plan or mutation.

Every phase emits JSON. Stop on any issue or incomplete receipt and follow its next action; do not continue from copied legacy telemetry or retry a partial mutation blindly. Preparation leaves legacy state and collector settings in place. Verification accepts exact tail bytes only when that same seat has newer paired context and provider samples under state/; finalization revalidates the accepted tails, copies the library without overwrite, and switches config last. The helper never removes the legacy telemetry or library. Retirement follows separate stable runtime, writer, reader, and recovery proof. Daemon, database, seat, plugin, and release lifecycle actions remain agent-owned.

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 the topology in a live graph with explorer, node detail, and system log
• Discover existing Claude Code and Codex sessions in tmux and adopt them into a managed rig
• Snapshot the full topology on rig down, restore by name with rig up <name>
• Communicate across agents with rig send, rig broadcast, and rig chatroom
• Evolve running topologies with rig expand, rig shrink, rig launch, rig remove

Every agent runs in a tmux session you can attach to, inspect, and work with directly.

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
rig up product-team

Use it when you want the week-one experience OpenRig is built around: an orchestrator HA pair, development work, review work, and enough moving pieces for the coordination layer to matter.

For a smaller starter, use conveyor:

rig specs preview conveyor
rig up conveyor

conveyor is the smallest shippable software factory, one command. It keeps the footprint lower for single-plan users while still showing a real handoff path through intake, planning, build, and review.

Also ships: implementation-pair, adversarial-review, research-team, and secrets-manager (HashiCorp Vault managed by a specialist agent).

Browse the library:

rig specs ls

How It Works

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

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

• CLI: 40+ commands designed for both humans and agents. Every mutating command ends with what happened, current state, and next action.
• UI: Explorer sidebar, topology graph with pod grouping, node detail panel, system log, chatroom.
• MCP: 17 tools so agents can manage their own topology (rig_up, rig_ps, rig_send, rig_chatroom_send, etc.)
• Runtimes: Claude Code, Codex, and terminal nodes. Adapters for Pi and OpenCode in development.

Key Concepts

• RigSpec: Declarative multi-agent harness definition in YAML. Pods, members, edges, continuity policies, culture file.
• AgentSpec: Reusable agent blueprint with skills, guidance, hooks, profiles, and startup contracts.
• Pod: Bounded context group. Agents in a pod share memory and can maintain each other's 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. Restore reports per-node outcomes (resumed, fresh, or failed).
• RigBundle: Portable archive with vendored AgentSpecs and SHA-256 integrity. Share topologies across machines.
• Culture: CULTURE.md sets coordination norms for the group. Research rigs get exploratory culture. Implementation rigs get conservative, trust-but-verify culture.

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.

rig up secrets-manager
rig env status secrets-manager
rig send vault-specialist@secrets-manager "Check Vault health and report status." --verify

Requires Docker for service-backed rigs.

Requirements

• Node.js 20, 22, or 24 (even-numbered LTS releases; odd releases like 25 lack native addon prebuilds)
• tmux

Optional:

• cmux for Open CMUX node surface controls
• Docker for service-backed rigs and managed apps

Setup and Troubleshooting

• rig setup attempts core machine preparation: tmux, cmux, Claude Code, Codex, and tmux defaults. It reports what it tried and what actually succeeded. If something fails, it gives the local agent enough context to finish the job.
• rig setup --full attempts a broader operator workstation setup (jq, gh) on top of core.
• rig doctor inspects current system health and helps diagnose problems after setup. Use it when something stops working or after machine changes.

Both commands support --json for agent-driven workflows.

Managed runtime boot (during rig up) may modify runtime config for core bootstrap and spec-selected runtime resources. rig setup discloses these paths so agents know what may be changed:

• global Claude: ~/.claude/settings.json for minimal OpenRig command allowlisting
• global Claude state: ~/.claude.json for managed workspace trust and onboarding completion
• project Claude: .claude/settings.local.json for context collector/activity hooks and selected claude_settings_fragment resources
• project Claude MCP: .mcp.json for selected claude_mcp_fragment resources
• global Codex: ~/.codex/config.toml for workspace trust and selected codex_config_fragment resources

Already-running adopted sessions may need restart before they pick up newly written runtime config.

For agents: Ask the user whether they want core setup (rig setup) or the fuller workstation path (rig setup --full) before choosing the invocation. Inspect the result with --json and use rig doctor to finish any remaining machine-specific issues.

Comparison with Claude Managed Agents

Anthropic shipped Claude Managed Agents — a cloud-hosted, Claude-only runtime at $0.08/session-hour. OpenRig is the local side: open source, cross-harness, runs on your machine, costs nothing.

Full comparison

Links

• Website: openrig.dev
• Blog: Why I Built OpenRig
• Docs: openrig.dev/docs
• Open Specification: openrig.dev/specs
• Twitter: @_feralmachine

License

Apache 2.0