MCPcopy Create free account
hub / github.com/mvschwarz/openrig

github.com/mvschwarz/openrig @v0.6.3

Chat with this repo
repository ↗ · DeepWiki ↗ · release v0.6.3 ↗ · + Follow
13,882 symbols 53,607 edges 2,519 files 1,170 documented · 8% ● updated 44d agov0.6.5 · 2026-10-04★ 5,02877 open issues

Browse by type

⨍ Functions 10,847◇ Types & classes 3,035
What it actually does AI analysis from the code graph
loading…
README

OpenRig

npm version npm downloads License: Apache 2.0 GitHub stars

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.

Guide: Getting started · Stuck? Help · Questions: Q&A · Updates and demos: @_feralmachine on X

See it running

The OpenRig TUI: the build rig as a graph, then as a table of seats with runtime, model, context and state, then one seat in detail (real recording, 10 seconds)

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

Not setting this up today? Get the next walkthrough and occasional OpenRig updates → https://openrig.dev/follow

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 (compatibility history). 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.

Choose the working account you already have: Claude Code, Codex, or both. Reuse an explicit choice; no second subscription is required. rig setup --dry-run previews the broader setup, but applying rig setup checks both harnesses and cmux. It is optional for the selected-provider path.

Before launching, your agent asks once: “Allow your agents to run OpenRig commands without repeated permission prompts?” Yes — recommended / No — keep prompts. This covers every rig command, including starting/stopping agents and configuration, at personal project scope unless you explicitly choose user-wide sessions. It is not global YOLO or permission to invent work. On Yes, the agent adds and verifies native rules; No or no answer leaves settings unchanged. An existing explicit choice is reused. Say “Undo the OpenRig command allowances added by this setup” to remove only its additions.

Check tmux -V and only your selected CLI/login: claude --version plus claude auth status, or codex --version plus codex login status. If needed, sign in once with claude auth login or codex login; do not install or log in to an unused provider.

Team Starter Models
Two Codex agents first-project Both gpt-6-astra (unchanged)
Two Claude agents first-project-claude Configured native Claude default
Claude owner + Codex checker first-project-mixed Claude default + gpt-6-astra

All three use the same owner/checker roles and task. Show the selected runtime, configured model and command before launch; confirm the account supports the model instead of silently falling back. The kernel starts automatically and selects from available authenticated providers independently of these two project agents. A missing unused provider is not a setup requirement.

cd /path/to/your/repository
starter=first-project  # or first-project-claude or first-project-mixed
rig specs preview "$starter" --kind rig
rig up "$starter" --cwd . --plan
rig up "$starter" --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 "$starter" 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@$starter" 'Implement <one useful change>. Track the task in the queue and return its ID. Keep it local, verify the behavior, ask dev-check in this rig to check the exact candidate, and record the result and how I can try it.'
rig queue list --destination "dev-owner@$starter" --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. The guided first-use path covers readiness, a useful task, a reviewed result, Herdr/cmux terminals and recovery.

Not setting this up today? Get the next walkthrough and occasional OpenRig updates → https://openrig.dev/follow

Community

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.

When What changes and why
npm installation Installs the CLI, bundled components and dependencies under your npm prefix (with Bun, under Bun's global directory). OpenRig's postinstall checks the Node.js version and that the SQLite module loads; Bun may block this script. It does not run daemon or provider setup.
rig setup Attempts missing tools and writes an OpenRig block in ~/.tmux.conf for mouse support and scrollback. On macOS it can install cmux and enable its automation socket control in ~/.config/cmux/settings.json. --full adds workstation tools. --dry-run shows setup's plan without applying it.
Daemon startup Creates/updates instance state under OPENRIG_HOME (normally ~/.openrig), including its database and managed plugin resources. Seeds the openrig-skills discovery skill in ~/.claude/skills and ~/.agents/skills, subject to existing version ownership. With runtime.codex.hooks_enabled enabled (the default), writes Codex hook configuration and trust records as described below—even before a rig launches.
Rig/seat launch and attachment Creates tmux sessions, supplies seat identity and daemon connection environment, and projects selected guidance, skills, plugins and runtime resources into the workspace. Managed startup pre-trusts the workspace. Claude context collection can also be provisioned for attached sessions and refreshed during monitoring.
Explicit permission configuration The built-in bootstrap does not add rig command allow rules. Agent-guided setup recommends Yes and requires your actual answer before the agent adds rules at your chosen scope. No/no answer preserves settings; existing choices and stricter rules remain relevant. Broader access is separate.

The provider files are separate from instance state. Here ~ means the daemon user's home; changing OPENRIG_HOME alone does not isolate provider configuration.

  • Claude Code: managed startup writes workspace trust and onboarding completion to ~/.claude.json. In the workspace, .claude/settings.local.json receives the context collector's statusLine command and selected activity hooks; helper scripts live under .openrig/. Selected settings/MCP resources can also change that settings file and .mcp.json. The shared settings resource sets permissions.defaultMode to acceptEdits and enables Exa/Context7 MCP entries; selected MCP resources configure those external services. Built-in bootstrap no longer writes a command allowlist to ~/.claude/settings.json or removes older allowances. The trust writer uses the daemon home, so a custom CLAUDE_CONFIG_DIR is not a general relocation of these writes.
  • Codex: writes the daemon's CODEX_HOME/config.toml (normally ~/.codex/config.toml). Startup enables hooks, adds the OpenRig activity relay commands and pre-writes trust hashes for those commands. Seat startup adds trust_level = "trusted" for the workspace; selected config resources can add MCP settings. Recognized update notices can be skipped during launch, recording the skipped version in Codex's cache; this is not an update install.

Activity relays send event type/subtype, seat/runtime identity, timestamps and native session identity to the configured OpenRig daemon's /api/activity/hooks endpoint, using its activity token. That payload excludes prompt text and tool arguments. Claude's collector writes context/token usage, session/transcript-path metadata and available rate-limit data to the instance's state/context-usage and state/provider-usage. Provider and selected MCP connections have their own data flows. Daemon plugin initialization also checks the OpenRig plugin release endpoint on GitHub.

Managed launches supply HOME, CODEX_HOME and OPENRIG_* identity/connection variables. Claude uses --permission-mode acceptEdits and defaults to the classic renderer for terminal scrollback. Codex uses -s workspace-write unless a named profile governs its sandbox; the default does not force an approval-policy flag. Fresh Codex launches also add writable access to the workspace's .git and the pod's shared queue-state directory with --add-dir; the shared root comes from OPENRIG_SHARED_DOCS_ROOT or ~/.openrig/shared-docs. YOLO is off by default. An explicitly selected full-bypass policy selects Claude's --dangerously-skip-permissions or Codex's -s danger-full-access -a never. The legacy environment-only OPENRIG_YOLO=1 path still selects only Codex's sandbox; a resolved policy overrides that environment setting.

Permission mode controls native execution permissions; work posture is separate project guidance. Use rig policy permissions list|show|current|apply for rig policy configuration (the four rig policy aliases remain compatible). Use rig seat set-permissions <seat> --mode <mode> --reason <text> for an audited future-launch choice: floor, full_bypass, or inherit to clear the seat override. Additional Claude modes such as auto require support from the exact managed Claude executable at the seat's working directory; selection and launch each check it. Unsupported or changed contexts refuse without a fallback. This does not relaunch the seat or change its current native process, history, rules or hooks. rig seat status separates the desired selection from the last launch arguments; neither proves native enforcement. See the permission guide.

Managed hook blocks target OpenRig's entries and retain unrelated hooks, but trust entries, selected resource keys and Claude's existing status-line command can be replaced. Some writers recover unreadable settings as empty objects; this is not a complete preservation or rollback guarantee. Back up relevant files before first use. Daemon/bootstrap writes are automatic and do not each have an interactive preview; rig setup --dry-run does not preview every later startup effect.

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

Extension points exported contracts — how you extend this code

browse all types & interfaces →

Core symbols most depended-on inside this repo

browse all functions →

Shape

Function 8,625
Interface 2,421
Method 2,222
Class 614

Languages

TypeScript100%
Python1%

Modules by API surface

packages/daemon/src/domain/queue-repository.ts97 symbols
packages/daemon/src/domain/types.ts81 symbols
packages/daemon/src/adapters/tmux.ts72 symbols
packages/daemon/src/adapters/codex-runtime-adapter.ts72 symbols
packages/tui/src/execution/execution-model.ts60 symbols
packages/tui/src/daemon-client.ts59 symbols
packages/cli/src/daemon-lifecycle.ts59 symbols
packages/cli/src/commands/scope.ts57 symbols
packages/daemon/src/domain/session-transport.ts56 symbols
packages/daemon/src/domain/review/compose.ts56 symbols
packages/daemon/src/domain/restore-check-service.ts55 symbols
packages/daemon/src/adapters/claude-code-adapter.ts54 symbols

Dependencies from manifests, versioned

@fontsource-variable/jetbrains-mono5.2.8 · 1×
@fontsource-variable/space-grotesk5.2.10 · 1×
@fontsource/inter5.2.8 · 1×
@hono/node-server1.13.0 · 1×
@hono/node-ws1.3.1 · 1×
@modelcontextprotocol/sdk1.28.0 · 1×
@radix-ui/react-dialog1.1.15 · 1×
@radix-ui/react-separator1.1.8 · 1×
@radix-ui/react-slot1.2.4 · 1×
@tanstack/react-query5.95.2 · 1×

Datastores touched

appDatabase · 1 repos

For agents

$ claude mcp add openrig \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact

Ask about this repo answers extend the page