{"slug": "openrig-multi-agent-harness", "title": "OpenRig: Multi-Agent Harness", "summary": "OpenRig released @openrig/cli, a multi-agent harness that lets developers define an agent team in YAML and boot it with one command, running Claude Code and Codex in the same rig. The tool requires Node.js 20, 22 or 24 plus tmux, installs via `npm install -g @openrig/cli` or `bun add -g @openrig/cli`, and writes provider hooks and workspace trust settings on launch, so the project advises running `rig setup --dry-run` and backing up relevant files first.", "body_md": "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.\n\nOpenRig 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.\n\nRequires 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](#what-openrig-changes-on-your-machine) and back up the relevant files.\n\n```\nnpm install -g @openrig/cli\nrig setup --dry-run\n```\n\nTo 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](#what-openrig-changes-on-your-machine) does not run at install time.\n\nReview 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.\n\nBefore launching, ask your agent to [configure your chosen permissions](https://github.com/mvschwarz/openrig/blob/main/docs/reference/getting-started.md#have-your-agent-configure-permissions): keep prompts, remember selected commands, or deliberately choose broader access. The agent handles setup and verification; OpenRig's shipped defaults stay unchanged.\n\nCheck prerequisites in your launch shell:\n\n```\ntmux -V\ncodex --version\ncodex login status\n```\n\nResolve missing tools or login before continuing. From your repository, inspect the plan before launching the two Codex seats, an owner and a checker:\n\n```\ncd /path/to/your/repository\nrig up first-project --cwd . --plan\nrig up first-project --cwd .\nrig tui --shared\n```\n\nThe 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.\n\nCheck 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:\n\n```\nrig 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.'\nrig queue list --destination dev-owner@first-project --limit 1000\n```\n\nSending 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](https://github.com/mvschwarz/openrig/blob/main/docs/reference/getting-started.md) covers readiness, a useful task, a reviewed result, Herdr/cmux terminals and recovery.\n\n- **Questions:**[Discussions › Q&A](https://github.com/mvschwarz/openrig/discussions/categories/q-a)\n- **Bugs and feature requests:**[open an issue](https://github.com/mvschwarz/openrig/issues/new/choose)\n- **Contributing:**[CONTRIBUTING.md](https://github.com/mvschwarz/openrig/blob/main/CONTRIBUTING.md) ·[Code of Conduct](https://github.com/mvschwarz/openrig/blob/main/CODE_OF_CONDUCT.md) ·[Security policy](https://github.com/mvschwarz/openrig/blob/main/SECURITY.md) ·[Getting help](https://github.com/mvschwarz/openrig/blob/main/.github/SUPPORT.md)\n- **Videos:**[youtube.com/@openrig](https://www.youtube.com/@openrig)\n- **Releases:**[GitHub Releases](https://github.com/mvschwarz/openrig/releases) and npm`@openrig/cli`\n\nWe aim to acknowledge issues and pull requests within one day; see [CONTRIBUTING.md](https://github.com/mvschwarz/openrig/blob/main/CONTRIBUTING.md#what-to-expect-from-us) for review targets.\n\nOpenRig writes instance state, provider integration and workspace files as part\nof setup and operation. These include **trust settings and executable hooks**.\nThe summary below follows this source revision; check `rig --version` when\nusing a published package, since repository guidance can be ahead of npm.\n\n| When | What changes and why | \n|---|---|\n| **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. | \n| **`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. | \n| **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. | \n| **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. | \n| **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](https://github.com/mvschwarz/openrig/blob/main/docs/reference/getting-started.md#have-your-agent-configure-permissions) ; existing rules remain relevant. Broader access is a separate choice. | \n\nThe provider files are separate from instance state. Here `~` means the daemon\nuser's home; changing `OPENRIG_HOME` alone does not isolate provider configuration.\n\n- **Claude Code:** managed startup writes workspace trust and onboarding completion\nto`~/.claude.json` . In the workspace,`.claude/settings.local.json` receives\nthe context collector's`statusLine` command and selected activity hooks;\nhelper scripts live under`.openrig/` . Selected settings/MCP resources can also\nchange that settings file and`.mcp.json` . The shared settings resource sets`permissions.defaultMode` to`acceptEdits` and enables Exa/Context7 MCP entries;\nselected MCP resources configure those external services. Built-in bootstrap\nno longer writes a command allowlist to`~/.claude/settings.json` or removes\nolder allowances. The trust writer uses the daemon home, so a custom`CLAUDE_CONFIG_DIR` is not a general relocation of these writes.\n- **Codex:** writes the daemon's`CODEX_HOME/config.toml` (normally`~/.codex/config.toml` ). Startup enables hooks, adds the OpenRig activity relay\ncommands and pre-writes trust hashes for those commands. Seat startup adds`trust_level = \"trusted\"` for the workspace; selected config resources can\nadd MCP settings. Recognized update notices can be skipped during launch,\nrecording the skipped version in Codex's cache; this is not an update install.\n\nActivity relays send event type/subtype, seat/runtime identity, timestamps and\nnative session identity to the configured OpenRig daemon's `/api/activity/hooks`\nendpoint, using its activity token. That payload excludes prompt text and tool\narguments. Claude's collector writes context/token usage, session/transcript-path\nmetadata and available rate-limit data to the instance's `state/context-usage`\nand `state/provider-usage`. Provider and selected MCP connections have their own\ndata flows. Daemon plugin initialization also checks the OpenRig plugin release\nendpoint on GitHub.\n\nManaged launches supply `HOME`, `CODEX_HOME` and `OPENRIG_*` identity/connection\nvariables. Claude uses `--permission-mode acceptEdits` and defaults to the classic\nrenderer for terminal scrollback. Codex uses `-s workspace-write` unless a named\nprofile governs its sandbox; OpenRig does not force an approval-policy flag.\nFresh Codex launches also add writable access to the workspace's `.git` and the\npod's shared queue-state directory with `--add-dir`; the shared root comes from\n`OPENRIG_SHARED_DOCS_ROOT` or `~/.openrig/shared-docs`.\nYOLO is **off by default**. Explicit `OPENRIG_YOLO=1` or a full-bypass seat policy\nselects Claude's `--dangerously-skip-permissions` or Codex's\n`-s danger-full-access`; a resolved seat policy takes precedence over the\nenvironment setting.\n\nManaged hook blocks target OpenRig's entries and retain unrelated hooks, but\ntrust entries, selected resource keys and Claude's existing status-line command\ncan be replaced. Some writers recover unreadable settings as empty objects;\nthis is not a complete preservation or rollback guarantee. Back up relevant\nfiles before first use. Daemon/bootstrap writes are automatic and do not each\nhave an interactive preview; `rig setup --dry-run` does not preview every later\nstartup effect.\n\nOpenRig 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.\n\n- **Define** topologies in YAML (RigSpec) with pods, edges, and continuity policies\n- **Boot** everything with`rig up` — tmux sessions, harnesses, startup files, readiness checks\n- **See** rigs, pods, and seats in the TUI topology table and graph; inspect projects, specs, feeds, and instance health\n- **Discover** existing Claude Code and Codex sessions in tmux and adopt them into a managed rig\n- **Snapshot** the topology with`rig down --snapshot` , restore by name with`rig up <name>`\n- **Communicate** across agents with`rig send` ,`rig broadcast` , and`rig chatroom`\n- **Evolve** running topologies with`rig grow` ,`rig shrink` ,`rig launch` ,`rig remove`\n\nEvery agent runs in a tmux session you can attach to, inspect, and work with directly.\n\nUse `first-project` for the focused first-use path. `product-team` is an optional\nlarger product-development example:\n\n```\nrig specs preview product-team --kind rig\nrig up product-team\n```\n\nUse it when you want a larger product squad: two orchestrators, implementation, QA, design, and two independent reviewers.\n\nFor a smaller starter, use `conveyor`:\n\n```\nrig specs preview conveyor --kind rig\nrig up conveyor\n```\n\n`conveyor` is a four-seat starter mixing Claude Code and Codex. It shows a handoff path through intake, planning, build, and review; `first-project` remains the smaller two-seat starting point.\n\nAlso ships: `implementation-pair`, `adversarial-review`, `research-team`, and `secrets-manager` (HashiCorp Vault managed by a specialist agent).\n\nBrowse the library:\n\n```\nrig specs ls\n```\n\nOpenRig is a local daemon + CLI + terminal UI + MCP server, built on tmux. The older React web UI remains in maintenance mode with best-effort support.\n\n```\nCLI / TUI / MCP\n      |\nHono HTTP daemon\n      |\n  Domain services\n      |\n  SQLite + tmux + runtime adapters\n```\n\n- **CLI** : Commands for both humans and agents to launch teams, inspect state, send messages, track owned work, and manage context.\n- **TUI** : Topology explorer, table and graph views, seat details, Specs, Projects, Terminals, Feed, and System. Navigate with the keyboard, mouse, or command bar.\n- **MCP** : Tools so agents can manage their own topology (`rig_up` ,`rig_ps` ,`rig_send` ,`rig_chatroom_send` , etc.)\n- **Runtimes** : Native Claude Code and Codex sessions, terminal nodes, and a Pi adapter using an RPC runner inside a terminal pane.\n\nThe TUI shows the team's coordination state; herdr and cmux show the actual agent terminals alongside it. Use `rig tui commands` to list the TUI's command-bar navigation, or [try the interactive TUI tour](https://openrig.dev/tour/workspace).\n\n*Captured from the interactive TUI demo using fictional project data.*\n\nWith herdr installed and connected, open the starter's terminals together:\n\n```\nrig terminal open first-project --provider herdr\n```\n\nFor cmux, use `--provider cmux`. The underlying sessions remain accessible through tmux. See the [terminal workspace guide](https://github.com/mvschwarz/openrig/blob/main/docs/reference/getting-started.md#share-the-dashboard-and-return-to-it) for setup and returning to an existing view.\n\n- **RigSpec** : Declarative multi-agent harness definition in YAML. Pods, members, edges, continuity policies, culture file.\n- **AgentSpec** : Reusable agent blueprint with skills, guidance, hooks, profiles, and startup contracts.\n- **Seat** : A stable role and address in a rig, such as`dev-owner@first-project` . The conversation occupying it can change while its identity and authored context remain.\n- **Pod** : A group of related seats with shared guidance and context. Each agent still has its own context window.\n- **Discovery** :`rig discover` fingerprints existing tmux sessions.`rig adopt` brings them under management.\n- **Snapshot/Restore** :`rig down --snapshot` captures full state.`rig up <name>` restores from latest snapshot. Restore reports per-node outcomes (resumed, fresh, or failed).\n- **RigBundle** : Portable archive with vendored AgentSpecs and SHA-256 integrity. Share topologies across machines.\n- **Culture** : CULTURE.md sets coordination norms for the group. Research rigs get exploratory culture. Implementation rigs get conservative, trust-but-verify culture.\n\nA 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.\n\n```\nrig up secrets-manager\nrig env status secrets-manager\nrig send vault-specialist@secrets-manager \"Check Vault health and report status.\" --verify\n```\n\nRequires Docker for service-backed rigs.\n\nFor an existing installation, follow the [upgrade procedure](https://github.com/mvschwarz/openrig/blob/main/skills/_canonical/core/openrig-upgrade/SKILL.md) and the [0.5.14 release notes](https://github.com/mvschwarz/openrig/blob/main/docs/releases/v0.5.14.md). Preserve live seats during the upgrade; `rig down` is not an upgrade step.\n\nThe migration below still applies when upgrading from a pre-0.5.9 instance.\n\n0.5.9 makes `$OPENRIG_HOME/context` the addressable context library, writes\nClaude telemetry to `state/context-usage` (and provider telemetry to\n`state/provider-usage`), and installs the default System World at\n`context/system/system-world.yaml`. Existing instances cross this boundary by\nan **Agent-Operated Migration** from the shipped `openrig-upgrade` skill. The\ntarget runtime reads canonical-first with legacy-fallback while new writes use\nthe canonical roots; a custom context-library root stays stable during\nactivation. This is not a directory rename to do while an old collector writes.\n\n```\n# SKILL_DIR is the installed openrig-upgrade skill directory.\nnode \"$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs\" --help\nnode \"$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs\" --home \"$OPENRIG_HOME\"\nnode \"$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs\" --home \"$OPENRIG_HOME\" --apply-state --preimage /safe/path/layout-0.5.9-before\n\n# Activate the exact target runtime separately. After every bounded legacy tail is followed by newer paired samples at both new state roots:\nnode \"$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\n\n# Run the separately invoked non-destructive finalizer only with that exact receipt:\nnode \"$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\n\n# Restore only helper-owned preparation/finalizer effects if the observed upgrade must be reversed:\nnode \"$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs\" --home \"$OPENRIG_HOME\" --rollback /safe/path/layout-0.5.9-before\n```\n\n`--help` prints the phase grammar without inventorying the instance. No phase\nflag intentionally runs the read-only plan; unknown options fail nonzero before\nplan or mutation.\n\nEvery phase emits JSON. Stop on any issue or incomplete receipt and follow its\n`next` action; do not continue from copied legacy telemetry or retry a partial\nmutation blindly. Preparation leaves legacy state and collector settings in\nplace. Verification accepts exact tail bytes only when that same seat has newer\npaired context and provider samples under `state/`; finalization revalidates the\naccepted tails, copies the library without overwrite, and switches config last.\nThe helper never removes the legacy telemetry or library. Retirement follows\nseparate stable runtime, writer, reader, and recovery proof. Daemon, database,\nseat, plugin, and release lifecycle actions remain agent-owned.\n\n- Node.js 20, 22, or 24 (the supported versions in this release)\n- tmux\n\nOptional:\n\n- herdr or cmux for terminal workspaces showing the agents together\n- Docker for service-backed rigs and managed apps\n\n- `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.\n- `rig setup --full` attempts a broader operator workstation setup (jq, gh) on top of core.\n- `rig doctor` inspects current system health and helps diagnose problems after setup. Use it when something stops working or after machine changes.\n\nBoth commands support `--json` for agent-driven workflows.\n\nBefore setup or managed launch, review [what OpenRig changes on your machine](#what-openrig-changes-on-your-machine), including provider trust, hooks and selected runtime resources.\n\nAlready-running adopted sessions may need restart before they pick up newly written runtime config.\n\n**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.\n\nOpenRig is open source and self-hosted, with Claude Code and Codex in the same team. You operate it on your own infrastructure; the selected providers' model usage costs still apply.\n\n- **Website** :[openrig.dev](https://openrig.dev)\n- **Docs** :[openrig.dev/docs](https://openrig.dev/docs) ([documentation index for agents](https://openrig.dev/llms.txt) )\n- **Blog** :[openrig.dev/blog](https://openrig.dev/blog) ·[Why I Built OpenRig](https://esoteric.run/blog/why-i-built-openrig)\n- **Open Specification** :[openrig.dev/specs](https://openrig.dev/specs)\n- **Videos** :[youtube.com/@openrig](https://www.youtube.com/@openrig)\n- **X** :[@_feralmachine](https://twitter.com/_feralmachine)\n- **Follow the project** :[openrig.dev/follow](https://openrig.dev/follow)\n\nApache 2.0", "url": "https://wpnews.pro/news/openrig-multi-agent-harness", "canonical_source": "https://github.com/mvschwarz/openrig", "published_at": "2026-09-28 01:48:09+00:00", "updated_at": "2026-09-28 02:00:54.914393+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-products"], "entities": ["OpenRig", "@openrig/cli", "Claude Code", "Codex", "Node.js", "tmux", "Bun", "GitHub"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/openrig-multi-agent-harness", "markdown": "https://wpnews.pro/news/openrig-multi-agent-harness.md", "text": "https://wpnews.pro/news/openrig-multi-agent-harness.txt", "jsonld": "https://wpnews.pro/news/openrig-multi-agent-harness.jsonld"}}