mvschwarz/openrig

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. Install and first run Requires Node.js 20, 22 or 24 and tmux. 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 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. The guided first-use path covers readiness, a useful task, a reviewed result, Herdr/cmux terminals and recovery. 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. When What changes and why npm installation Installs the CLI, bundled components and dependencies under your npm prefix. OpenRig's postinstall checks Node/SQLite compatibility; 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. Ask your agent to apply your chosen project or user scope ; existing rules remain relevant. Broader access is a separate choice. 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; OpenRig 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 . Explicit OPENRIG_YOLO=1 or a full-bypass seat policy selects Claude's --dangerously-skip-permissions or Codex's -s danger-full-access ; a resolved seat policy takes precedence over the environment setting. 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.