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 is open-source software for building and running your own network of agents. It 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.

It's the open-source system behind my AI civilization experiments.

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

See it running

Start here: the guided first-use path: install, talk to the kernel operator, then choose a team for your first useful change.

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

Install and first run

Let your coding agent set it up. First check that node --version shows 22 or 24: the command below needs Node.js and the npx that comes with it. Then, in your project folder, add OpenRig's rigs skill to the agent you use:

# Claude Code
npx skills add https://github.com/mvschwarz/openrig/tree/v0.7.5/skills/rigs --skill rigs --agent claude-code
# Codex
npx skills add https://github.com/mvschwarz/openrig/tree/v0.7.5/skills/rigs --skill rigs --agent codex

Then type /rigs in Claude Code, or $rigs in Codex, and say what you want built. The skill has your agent tell you what it will run and change before it does, install OpenRig, open the OpenRig view and pass your goal to OpenRig's operator.

You need Node.js 22 or 24 (22 on Apple silicon), tmux, macOS or Linux (WSL2 on Windows), and Claude Code or Codex signed in. One provider is enough to start.

Already have OpenRig? Use the tag that matches rig --version, or upgrade first.

Prefer to type the commands yourself? Install it yourself ↓

Requires Node.js 22 or 24 and tmux, on macOS or Linux, and one working Claude Code or Codex account: one is enough, since the kernel operator adapts the shipped starter team to whichever you have. On Linux, the distribution's own Node.js can be older (Ubuntu 24.04's is 18); install a supported version with nvm (nvm install 22) or NodeSource. On a Mac with Apple silicon, use Node.js 22 (compatibility history). On a Mac where you aren't an administrator, or where Homebrew belongs to another account (its brew install is refused), install Node.js in your own home folder with nvm: run touch ~/.zshrc (a new Mac account has none, and nvm's installer only adds itself to a profile file that already exists), then nvm's install command, for nvm v0.40.8 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash (nvm's page has the newest), open a new terminal, and run nvm install 22. nvm itself needs no administrator password, and npm install -g then installs into your nvm folder. If nvm's installer says you need Apple's command line tools, run xcode-select --install, then its install command again. On Windows, use WSL2, the Windows route OpenRig supports; native Windows isn't supported. OpenRig's automated tests don't run on WSL2 yet; see one user's working setup.

What OpenRig changes on your machine - Install: @openrig/cli goes in globally with npm. - Setup: rig setup adds an OpenRig block to ~/.tmux.conf. It can install tmux (with Homebrew on macOS), and Herdr unless you pass --no-herdr. Plain rig setup, which is what the one-command install runs, checks both Claude Code and Codex and may install a missing one; rig setup --providers claude (or codex) limits it to yours. - Starting OpenRig, for the coding agent you use (paths are the usual defaults): - Codex: hooks and trust in ~/.codex/config.toml. - Claude Code: workspace trust in ~/.claude.json, and activity hooks in the project's .claude/settings.local.json, plus a status line unless you already have your own. - Discovery skills go in ~/.claude/skills and ~/.agents/skills. - Starting a team in your project: adds managed guidance to AGENTS.md or CLAUDE.md, plus the team's skills and plugins. - Permissions: by default, OpenRig's own kernel gets broader permissions than a project team gets by default. On Codex that's full access with no approval prompts (-s danger-full-access -a never). On Claude Code, its file tools, web fetches and operational commands, including reads under your home folder, run without asking. A permission policy, per-agent choice or Codex profile changes that. What your team can do depends on the team you choose and your settings; workshop, for example, ships with broad access. - Backups: OpenRig doesn't guarantee it can preserve or roll back these files, so back them up first.

Everything OpenRig writes, and why →

Install it yourself

This runs OpenRig's install script from the v0.7.5 release. It checks Node.js and npm, installs the latest published @openrig/cli with npm install -g, runs the Node.js and SQLite check, then runs rig setup --dry-run and rig setup. The first line prints that plan and changes nothing:

curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.7.5/scripts/install.sh | sh -s -- --dry-run
curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.7.5/scripts/install.sh | sh

If a provider isn't signed in yet, the last step reports FAILED [4/4], and rig setup lists the sign-in under "Some steps need attention". If the only remaining failures are provider sign-ins, the install steps finished; sign in to each selected provider as below and continue.

Or step by step:

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.

npm 11 and later can skip that postinstall script and print npm warn install-scripts naming @openrig/cli. That's expected: the CLI still works, and only the Node.js and SQLite check was skipped. To run it yourself, use node "$(npm root -g)/@openrig/cli/scripts/check-abi.mjs"; rig doctor checks the Node.js version only.

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; applying rig setup checks both harnesses and installs a missing one, plus Herdr unless declined with --no-herdr. Pass the choice with --providers claude or --providers codex so the other reads not selected instead of failed. The one-command install above doesn't know the choice, so it installs and checks both; for one provider, go step by step and run rig setup --providers <choice>. On macOS, the installing agent offers Ghostty once. Setup leaves an existing cmux installation alone. It is optional for the selected-provider path.

A team seat with no permission policy, per-seat choice or (for Codex) named profile launches with OpenRig's team default: Claude runs ordinary rig commands, project reads and common tests without prompting, while lifecycle commands such as rig up and rig down still ask; Codex also gets the OpenRig workspace and its pod's state directory as writable directories. Before launching, your agent recommends keeping that default, and offers to remember selected OpenRig commands in your native settings only if you want that, 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 keeps the team default and leaves settings unchanged. An existing explicit choice is reused. Say “Undo the OpenRig command allowances added by this setup” to remove only its additions.

If permission prompts are slowing you down, consider the workshop bundle. It ships with broad access and non-interruptive mode: its agents bypass permission prompts and supported harness warning dialogs. The listing and before-install view explain that access before you choose it.

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.

Your agent opens OpenRig for you

After installing, your agent opens the OpenRig TUI and the operator for you. To get back to them