mvschwarz/openrig

▲ 4,045 stars today★ 8,553⑂ 706

Build your own network of agents from Claude Code, Codex and Pi: persistent teams with roles, shared context and owned work.

About mvschwarz/openrig

mvschwarz/openrig is an open-source project on GitHub, mainly written in TypeScript. Build your own network of agents from Claude Code, Codex and Pi: persistent teams with roles, shared context and owned work. It currently holds 8,553 stars and 706 forks with 130 open issues, and was last pushed on 2026-11-02 (repository created 2026-04-01).

Project Overview

Git Homed tracks it on the Today's Trending board.

GitHub Repository Details

Repository mvschwarz/openrig · default branch main · size 56115 KB · watchers 28 · source: GitHub REST API and repository README

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 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

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, 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 . 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 later, ask your agent for OpenRig or your agents in any words. After checking the selected login, it starts the daemon if it's stopped and opens the view:

rig daemon start
rig terminal open saved:kernel --window

--window opens a new terminal tab or window itself, or a space in your current Herdr session. Below 120 measured columns, the operator fills the first page; from 120, the dashboard and operator share it equally. The advisor has a separate tab or tmux window. An installing agent can run it from its shell on the daemon's desktop; the person copies nothing. It uses Herdr when installed, otherwise the same layout in plain tmux, and preserves existing conversations. rig tui is the team dashboard. Installation is finished when you are talking to the operator; if you choose to talk later, that handoff remains pending.

If setup stops, read the named step: missing tools and selected-provider logins need their specific setup action. A harness permission rule, sandbox or automatic permission decision can also block the installing agent's command. The agent should name the command and reported reason, then help you resolve that specific step within your chosen permissions. A permission refusal is not an OpenRig installation result.

The desktop may need an Automation approval; SSH/headless sessions may have no display. Herdr can show first-run panels, and an 80×24 window can cramp the view. Follow the OpenRig view checks and next steps. Herdr is visible only inside a terminal you can see. Changing the shared TUI to :terminals does not open that terminal. The agent checks the visible window when it has desktop access and says what it could not verify otherwise. Over headless SSH, it asks you to open a new terminal window or tab and gives the exact connection and attachment command for the current view. If you choose a manual attachment after a failure, ask the installing agent for the exact command using your current operator session; run that in a new terminal window.

The kernel's operator helps you pick a first team. It asks what you want to build, recommends one of three, and fits it to the providers you have.

| Team | Talk to | Agents and purpose | | --- | --- | --- | | starter | dev-build@starter | A Claude Code builder and Codex reviewer for one bounded change | | workshop | orch-lead@workshop | A lead, builder, QA and reviewer for ongoing work in one repository; a rig bundle the operator installs from its pinned listing | | factory | orch-lead@factory | Seven: a lead, advisor, build, QA, design and two independent reviewers for sustained product work |

As shipped, starter uses both Claude Code and Codex. With only one of them, ask the kernel operator to adapt it: it writes a copy of the team for your providers under the same name. The naming guide explains how their pods and roles grow and how to name your own team. first-project is starter's old name and still starts it, unless you already have a rig named first-project or starter: then it refuses and names the rig up --existing command that brings that rig back. 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 teams. A missing unused provider is not a setup requirement.

To launch the starter yourself instead (the manual path, without the operator):

cd /path/to/your/repository
rig specs preview starter --kind rig
rig up starter --cwd . --plan
rig up starter --cwd .

To see your agents, use rig terminal open saved:kernel --window. If that window cannot open, rig tui --shared is the named dashboard-only fallback; it does not show the operator conversation. The installing agent should resolve or explain the window failure, not finish by suggesting a command for you to type. 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. If a seat stopped at such a prompt before its startup context arrived, rig ps shows the rig seat continue command that delivers it once the prompt is answered. Then give the builder one bounded outcome from your repository:

rig send dev-build@starter 'Implement . Track the task in the queue and return its ID. Keep it local, verify the behavior, ask dev-review in this rig to check the exact candidate, and record the result and how I can try it.'
rig queue list --destination dev-build@starter --limit 1000

Sending a message does not itself create a queue item; the builder records the task. Read the final artifact and the review of its exact candidate, then return to the same builder 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 (rig and openrig-tui), 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. Installs herdr by default on macOS and Linux unless declined with --no-herdr; an unavailable herdr install is a warning. On macOS the installing agent offers Ghostty, and --ghostty attempts it after acceptance. Existing cmux settings are left unchanged. --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, the refocusing skill and the person-facing rigs skill in ~/.claude/skills and ~/.agents/skills, subject to existing version ownership. When a Codex seat is already recorded and runtime.codex.hooks_enabled is enabled (the default), ensures its hook configuration and trust records as described below. With no recorded Codex seat, enabled hooks wait for its first launch; disabled hooks still remove a stale OpenRig-managed hook block, if present. | | 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. In a Git repository, newly created files under .codex/plugins/shared:openrig-core/ (or the unqualified .codex/plugins/openrig-core/) are added to the repository's Git info/exclude inside an # BEGIN OpenRig generated files block; new AGENTS.md, CLAUDE.md and CLAUDE.local.md files stay visible with a warning. | | Bundle install (rig bundle install, or rig up with a .rigbundle or GitHub link) | Writes the bundle's files into the install target: --target, or the current directory for rig up and for a GitHub link. rig bundle install with a local archive needs --target. Routes its declared skills, plugins and context packs into your libraries. A GitHub link's archive is kept under OPENRIG_HOME/bundle-imports/, and installs are recorded in OPENRIG_HOME/bundle-audit.jsonl. A bundle that carries a project creates it under workspace.projects_root and records it, with the rig's association, in the workspace catalog. | | Explicit permission configuration | The built-in bootstrap does not add rig command allow rules to your settings files; a team seat with no permission policy, per-seat choice or (for Codex) named profile gets the per-launch team default instead. Agent-guided setup recommends keeping it and requires your actual answer before the agent adds remembered rules at your chosen scope. No/no answer keeps the team default and 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.

With an explicit permission mode, it uses the launch-selected HOME/.claude.json, or <CLAUDE_CONFIG_DIR>/.claude.json when that variable is set. Classic startup writes HOME/.claude.json, and also <CLAUDE_CONFIG_DIR>/.claude.json when the daemon has that variable set. In the workspace, .claude/settings.local.json receives the context collector's statusLine command and selected activity hooks; a user's own status-line command is preserved, so it can prevent collector installation. Selected settings resources can still replace overlapping keys. The collector script lives under .openrig/, and the activity-hook relay under the instance's state/claude-activity-hooks/. Selected settings/MCP resources can also change that settings file and .mcp.json. The shared settings resource enables Exa/Context7 MCP entries and leaves existing permissions.defaultMode and permission rules unchanged. Managed launch flags select the session mode. Selected MCP resources configure those external services. Built-in bootstrap no longer writes a command allowlist to ~/.claude/settings.json or removes older allowances. CLAUDE_CONFIG_DIR does not relocate the project-local writes. To keep your own status line alongside the collector, see Custom Claude status line. ~/.codex/config.toml). With hooks enabled, daemon startup ensures the OpenRig activity relay commands and their trust hashes when a Codex seat is already recorded; otherwise the first Codex launch does so. With hooks disabled, startup can remove a stale OpenRig-managed hook block even without a Codex seat. Seat startup adds trust_level = "trusted" for the workspace; selected config resources can add MCP settings. Managed launches pass -c check_for_update_on_startup=false, which writes no config; a recognized update notice that still appears can be skipped, 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. On that plain launch OpenRig first asks Codex for its own configuration and adds -c sandbox_workspace_write.network_access=true only when Codex answers that no configuration layer sets network access and no managed requirement could restrict it, so the seat can reach the local daem

GitHub Stars & Activity

8,553Stars
706Forks
130Open issues
TypeScriptLanguage

GitHub Popularity

GitHub stars8,553
Forks706
Open issues130
Primary languageTypeScript
LicenseApache-2.0
Stars gained today4,045
Created2026-04-01
Last pushed2026-11-02

Trending History

Monthly boardrank #60 · ▲ 4,045 stars

Related GitHub Projects

1

immich-app / immich

TypeScript★ 118,196⑂ 7,479▲ 104 stars
→
2

thedotmack / claude-mem

TypeScript★ 112,406⑂ 9,772▲ 1,165 stars
→
3

Fission-AI / OpenSpec

TypeScript★ 73,894⑂ 5,061▲ 117 stars
→
4

tashfeenahmed / freellmapi

TypeScript★ 47,307⑂ 6,462▲ 688 stars
→
5

pingdotgg / t3code

TypeScript★ 45,363⑂ 9,338▲ 3,173 stars
→
6

Crosstalk-Solutions / project-nomad

TypeScript★ 42,128⑂ 4,305▲ 204 stars
→
7

mattpocock / sandcastle

TypeScript★ 8,829⑂ 946▲ 31 stars
→
8

hieunc229 / mailflare

TypeScript★ 5,616⑂ 848▲ 74 stars
→

More Trending Repositories