OpenRig Makes Your Agent Team a File You Can Read Before It Runs
The Claude Code and Codex wrapper turns fan-out into something you declare instead of something that happens to you, and it rewrites your harness settings on the way in
How many agents are running on your behalf right now? For most people using Claude Code or Codex seriously, the honest answer is "some number I did not choose." One task spawns subagents, a subagent spawns more, and the headcount exists only as a side effect you discover in a process list or on an invoice.
That gap stopped being theoretical over the weekend. On September 26 a Codex customer posted on Hacker News that a simple UX validation request fanned out into 826 child agents and roughly $78,000 in charges, itemized at $79,664.88 across 162 invoices. It is one user's unverified account, and OpenAI has not responded publicly. But the shape of the story is familiar to anyone who has watched a harness decide on its own how much parallelism a job deserves.
OpenRig, sitting at #10 on Trendshift's daily board this morning, takes the opposite approach. Its README opens with the whole pitch in three lines: "A harness wraps a model. A rig wraps your harnesses. Define your agent team in YAML, boot it with one command."
Why a file matters
My position: the most useful thing OpenRig does is not coordination. It is making the team legible before it exists. A YAML file that lists every seat is something you can diff, review in a pull request, and read at 2 a.m. when the bill looks wrong. A harness that decides its own fan-out gives you none of that.
That matters because the config-key approach to limits has its own failure modes. Codex has an agents.max_threads setting, and an open issue, #33447, reports that when MultiAgentV2 becomes active it silently ignores that key and applies a different one, features.multi_agent_v2.max_concurrent_threads_per_session, instead. The reporter's summary: "Desktop silently started with the default four-slot limit," with nothing to say another path had superseded the one they set. In that case the silent override was a lower limit, not a higher one. The lesson still applies. A limit you wrote in one place and the runtime reads from another is not a limit you control.
How OpenRig is built
OpenRig is a TypeScript CLI, Apache-2.0 licensed to Mike Schwarz, at version 0.5.17 as of September 27. It wraps Claude Code and Codex natively, plus plain terminal nodes and a Pi adapter.
The vocabulary is the design, so it is worth getting right.
A RigSpec is the YAML file. The README describes it as a "declarative multi-agent harness definition" made of pods, members, edges, continuity policies and a culture file.
A seat is "a stable role and address in a rig, such as dev-owner@first-project." The key idea is in the next clause: "The conversation occupying it can change while its identity and authored context remain." A seat outlives any single session.
A pod is a group of related seats with shared guidance, and each agent in it keeps its own context window.
An AgentSpec is a reusable blueprint carrying skills, guidance, hooks, profiles and startup contracts.
Each seat runs in its own tmux session, which means you can attach to any agent and watch it or type into it directly. Seats talk to each other through rig send, rig broadcast and rig chatroom, and work queues are inspectable with rig queue list.
The starter project, first-project, launches two seats: an owner and a checker, both Codex agents. That pairing makes an argument of its own. The default team is one agent doing the work and one reviewing it, not a swarm.
Put this into practice
The lowest-friction path takes about ten minutes, most of it reading.
1. Check the prerequisites. You need Node.js 20, 22 or 24, and tmux, on macOS or Linux. On Apple silicon, the README says to use Node 22. Native Windows is not supported, and WSL2 has not been tested.
2. Back up two files first. Copy ~/.claude.json and ~/.codex/config.toml somewhere safe. The reason is in the limitations section below, and the README asks you to do this too.
3. Install and dry-run the setup.
npm install -g @openrig/cli
rig setup --dry-run
4. Read the plan before you launch. From your repository, run:
rig up first-project --cwd . --plan
This is the command that justifies the whole tool. It shows you the topology before anything boots: which seats, which harness each uses, how they connect. If the plan surprises you, that surprise is the thing you would otherwise have met on your invoice.
5. Decide permissions before the team starts. The getting-started guide says it plainly: "Choose permissions before starting the team." The starter defaults to Codex's -s workspace-write sandbox. Full bypass is off by default. You only get Claude's --dangerously-skip-permissions or Codex's -s danger-full-access by setting OPENRIG_YOLO=1 or choosing a full-bypass seat policy. Leave it off until you have watched a rig run.
6. Launch, send one task, watch the queue.
rig up first-project --cwd .
rig send dev-owner@first-project 'your task description'
rig ps --nodes --rig first-project
7. Commit the RigSpec. Once a team shape works, put the YAML in your repo. From then on, a change to how many agents run on this project is a reviewed diff.
Honest limitations
OpenRig solves a real problem and leaves several open. Here is where it stops.
It declares seats. It does not cap spend. I read the README and the getting-started guide looking for token budgets, cost ceilings or a maximum agent count, and found none. A RigSpec fixes how many seats exist. It does not, as far as I can tell from the docs, stop the Claude Code or Codex session inside a seat from spawning its own subagents. The headcount you can read is the top layer, not every layer, so keep the per-harness limits set too, and check which key your runtime actually reads.
It writes to your harness configuration. This is the cost of the convenience, and the README is upfront about it. Launching a rig "writes provider hooks and workspace trust settings." Claude Code records workspace trust and onboarding completion in ~/.claude.json. The daemon writes Codex hook configuration and trust records to CODEX_HOME/config.toml when Codex hooks are enabled. The README warns that while managed hook blocks keep unrelated hooks, "trust entries, selected resource keys and Claude's existing status-line command can be replaced." If you have tuned those files by hand, a first launch can overwrite that work. Back them up.
Setup touches more than the project. rig setup adds an OpenRig block to ~/.tmux.conf, and the daemon keeps state under ~/.openrig. None of it is hidden, and all of it is documented, but a tool that edits your shell environment deserves a read of that section before you install it.
It needs tmux and a Unix box. Every seat is a tmux session. That is what makes agents attachable and inspectable, and it also rules out native Windows for now.
It is young. Version 0.5.17, about 1.3k stars, and a fast release cadence. The repo shows more than 3,000 commits, which is momentum, not stability. Expect the RigSpec format to move.
It does not fix the 826-agent story. To be precise about the connection: nothing here would have changed a bug inside a Codex client build, if that is what the poster hit. What OpenRig changes is the default posture, from "the harness decides how many agents this job deserves" to "a file I reviewed says how many seats exist."
Headcount is a design decision
Every multi-agent setup makes a decision about how many agents run and who they report to. Most make it implicitly, inside a harness, at runtime, where nobody reviews it. OpenRig moves the top of that decision into a file you can read, diff and commit, and it is honest about what it changes on your machine to get there.
Run the plan command on a real project this week. If you cannot predict what it prints, you have learned something important about the agent team you already have.
Sources: mvschwarz/openrig README; OpenRig getting started; openai/codex issue #33447; Hacker News Codex report; Trendshift.
Medium metadata
- Title: OpenRig Makes Your Agent Team a File You Can Read Before It Runs
- Subtitle: The Claude Code and Codex wrapper turns fan-out into something you declare instead of something that happens to you, and it rewrites your harness settings on the way in
- Tags: AI Agents, Claude Code, Codex, Multi Agent Systems, Developer Tools
- Canonical URL: fervorai.dev (import from the published post)
- Reading time: about 8 minutes