FAQ

No. OpenRig works with your existing Claude or Codex subscription. Agents run as normal coding sessions in tmux. They use whatever authentication your coding agent already has. No separate API keys, no per-token billing, no usage dashboards to watch.

Claude Code, Codex, Pi and Oh My Pi, in any mix within one rig: each seat names its harness, and every agent messages the others and works the same queue. A Claude owner with a Codex checker is a common pairing, since different models catch different mistakes. Each seat can also have its own model and reasoning effort. See Mixed-harness teams, and the Claude vs Codex and Model diversity guides.

OpenRig is open source under the Apache 2.0 license. No cloud, no hosted service, no paid tier. It runs entirely on your machine. The open specification is CC-BY-4.0.

Each names something you'll need to talk about once you run more than a couple of agents. Claude Code or Codex is a harness around one agent. A rig is a team of them, grouped into pods, where each agent sits in a seat: a named position that outlasts whichever agent occupies it. A rig is described in a YAML rig spec, and each agent's role in an agent spec. See What is a rig? for how they fit, or the Taxonomy for the full list.

Terminal tabs give you parallel agents. OpenRig gives you a topology: agents with defined roles, grouped into pods with shared context, connected by communication edges, with lifecycle management.

The practical difference: reboot your machine with terminal tabs and you spend an hour reconstructing your setup. With OpenRig, run rig up my-rig and everything comes back: sessions, context, roles, the whole graph.

You have two ways to keep it going. With managed compaction turned on, OpenRig has a Claude agent write a restore map, compacts it, then has it read the map back, so it resumes instead of starting cold. When compaction isn't enough, rig handover puts a fresh agent in the same seat with a packet of what the last one was doing. See Managed compaction for Claude, Swap in a fresh agent and Continuity.

No. Start with one agent. Add a review pod when you need one. Research team later. Use rig discover to scan unmanaged sessions on request. If you already have tmux sessions running, rig discover fingerprints them; its --draft option generates a candidate RigSpec. See the Growing Organically guide.

A seat is a named position in a rig, such as dev-build@starter, that keeps its address, role and queued work when the agent in it changes. A pod is a group of seats whose work is closely tied: they share startup files and can carry their own continuity policy, while each agent keeps its own context window. A pod can mix Claude Code and Codex. See What is a rig? and Add agents to a running team.

macOS and Linux, with Node.js 22 or 24, tmux, and Claude Code or Codex installed and signed in. Only the harness your team uses has to be signed in. rig preflight checks Node, tmux, the daemon port and state folders before you start. See One-command install, macOS and Linux and Getting started.

Just use tmux. Seriously.

Every coding agent already runs in a terminal. tmux gives you named sessions that survive disconnects, inspectable output via capture-pane, input injection via send-keys, and session persistence across reboots. That's identity, communication, observability, and durability, all for free, from a tool that ships with every Linux server and every Mac.

OpenRig doesn't require agents to integrate with it, install a plugin, or even know they're being managed. It manages agents that have no idea OpenRig exists. That's only possible because tmux gives you a universal control surface beneath every terminal agent.

We see people build elaborate agent orchestration frameworks, custom IPC layers, and bespoke communication protocols, then hit a wall when they try to manage more than three agents. The answer is almost always: just use tmux. OpenRig is what happens when you take that idea seriously and build an entire control plane on top of it.

Yes, this is a first-class use case. OpenRig ships with 18 MCP tools that let any MCP-capable agent manage topologies programmatically: boot rigs, check node status, create snapshots, restore sessions, send messages to agents, and capture terminal output. The CLI is also designed for agent use: structured output, clear error messages, no interactive prompts.

No. OpenRig is a command-line tool (rig, from the npm package @openrig/cli) and a local daemon that run your Claude Code and Codex agents in terminal sessions. There's nothing to import: you use it from a terminal (rig up, rig send), or your coding agent drives it through the CLI or the MCP tools. See Getting started.

Those are orchestration frameworks: they define how agents talk to each other in code. OpenRig is a layer below: it manages the infrastructure that agents run on. It's closer to docker-compose than to a web framework.

You can run any harness framework inside OpenRig. The open specification (AgentSpec, RigSpec, RigBundle) is deliberately tool-independent. You define topology in YAML, and any compliant tool can boot it.

OpenRig is not a plugin. A plugin extends one tool: it adds a capability inside a single coding agent or harness, and it lives and dies with that one tool. OpenRig sits a layer above any single tool. It is the control plane that coordinates a whole topology of agent harnesses, the layer where you say which agents exist, how they are grouped, how they talk, and how they recover. A harness wraps a model. A rig wraps your harnesses.

One thing can cause confusion, so it is worth naming directly. OpenRig does have its own packaging mechanism called a plugin, managed with rig plugin: a way to bundle an extension so it can be discovered and used inside a rig. That is a component you can use within OpenRig. It is not what OpenRig itself is. OpenRig is the coordination layer; a plugin is one of the things you can package and run inside it.

Claude Code's agent teams are experimental and off by default. One Claude Code session starts Claude Code teammates that share a task list and message each other, and the team belongs to that session. OpenRig is for a team you keep. Each agent has a name and a role, and keeps its work through restarts, compaction and handover to a fresh agent. One team can mix Claude Code, Codex, Pi and Oh My Pi. Work goes through a task queue that outlives any session, and agents can run on more than one machine. OpenRig starts the real Claude Code and Codex CLIs on the logins you already have. See Mixed-harness teams, Restore after a restart or reboot and the full comparison with Claude Agent Teams.

Claude Managed Agents is a hosted runtime primitive: a way to run Claude agents in Anthropic's infrastructure.

OpenRig runs agent topologies on your own machine. You mix runtimes, group agents into pods, attach to any session directly, and recover the whole system after a restart.

It also picks up agents you already have running, sessions you launched yourself before OpenRig got involved, and shows the topology in the terminal UI, including its graph tab.

A harness framework wraps a base model with focus persistence, memory, tool use, and lifecycle management, turning a model into a productive coding agent. Examples include Claude Code's built-in harness, Codex CLI, GSD, G-Stack, Super Powers, and any custom setup you build.

OpenRig doesn't compete with harness frameworks. It manages the topology they run in. Build your own harness framework, or use an existing one.

Yes. A RigBundle is a portable archive that bundles a RigSpec plus all vendored AgentSpecs. Anyone with OpenRig installed can import and boot it. Think of it like a Docker image for agent topologies.

That depends on your machine and your subscriptions. OpenRig itself imposes no hard limit; it manages whatever your hardware can support. Each agent is a tmux session, so the overhead per agent is minimal.

There are two ways to work, and they trade off against each other.

The disposable way: start an agent, give it a task, and throw it away when the task is done. The next task gets a brand-new agent. Most multi-agent tools assume this. It is simple, and it sidesteps the whole problem of managing a context window over time.

The long-lived way: keep the same agent running across tasks and sessions. Manage its context window so it stays sharp, and when it has to compact, carry its identity and working knowledge over to a fresh session. Same agent, same role, fresh window.

The long-lived way tends to produce better results, for a practical reason. An agent that has been working on your codebase for three days has a feel for it that a fresh agent does not. It knows why you named things a certain way, which patterns you prefer, and what you tried last week that did not work. That accumulated judgment is expensive to rebuild from scratch every morning.

Most people start fresh anyway, because keeping an agent alive and in context has been fragile and tedious without tooling. That is the gap OpenRig is built to close. Persistent identity across sessions, shared memory within a pod, and snapshot-and-restore so a whole topology comes back by name. These are what make the long-lived way practical instead of painful.

Both ways are valid. Disposable agents are fine for narrow, context-light tasks. But if your agents need deep knowledge of a project, or you want them to build up judgment over time, keeping them alive is the better choice. There is a hard part still being worked on: saving the facts an agent learned about a codebase is relatively easy, but saving the reasoning behind its judgment, the why behind what it believes, is much harder to automate. Until that is fully solved, simply keeping a good agent running is the more reliable path.

No, and there are no plans for one. OpenRig is a local tool by design. Your code, your agents, your machine. The daemon is a local HTTP server with a SQLite database. Nothing phones home.

Install with npm install -g @openrig/cli, then run rig setup. When OpenRig starts, its operator asks what you want to build and recommends a team: workshop for most projects (a lead, a builder, QA and a reviewer, installed from its page on the rigs list), starter if you're new to agent teams (one builder and one reviewer), or factory for bigger work. To start the smallest team yourself, run rig up starter --cwd . in your repository; it needs both a Claude Code and a Codex login. See Three teams to start from and Getting started.

OpenRig writes marked blocks into each agent's CLAUDE.md or AGENTS.md (your own text stays), local settings and skills in the agent's folder, and a few marked entries in your user-level Claude and Codex config. It doesn't write ~/.claude/settings.json, and rig down removes the instruction blocks it wrote. rig setup --dry-run lists the main files it may touch. See Configuration.

Each agent's permissions come from its rig spec, a choice you saved for that agent, or a default. Since 0.6.6, team agents with none of those get a default that needs fewer prompts. Claude Code agents run rig commands, reads inside the project and common test commands such as npm test or pytest without a prompt, and still ask before starting, stopping or installing teams. Codex agents keep their workspace-write sandbox and can also write OpenRig's workspace and state folders. They don't ask before starting or stopping teams yet. The kernel's agents, which install and run teams for you, get wider defaults. These are command allowances, not containment: a project's test command runs project code. Your own Claude Code ask and deny rules still apply, and OpenRig writes no settings file. To keep the old prompts, give the rig or agent permission_policy: none. For full bypass, use builtin:yolo in the rig spec, or rig seat set-permissions for one agent, from its next launch. rig seat status shows each agent's mode and where it came from. One known issue: rig setup's permission question still describes the behaviour before these defaults, and its text is corrected in the next release.

Each agent starts with its culture, role and skills, written into its folder at launch. It pulls more when it needs it with rig context get, down to a single section. Each seat can also keep a LEARNED.md of lessons that stays with the position for the next agent. See Context on demand, Knowledge that outlasts the agent and Context.

You set that in the rig spec: each seat gets its role from an agent spec, and a delegates_to edge says who hands work to whom, and who gets alerted when it stalls. In the starter team, a Claude Code builder makes the change and hands it to a Codex reviewer through the queue, so you don't relay reviews between terminals. See Roles and delegation and Edge types.

Through a task queue: each task is assigned to one agent and keeps its full history, so it survives a busy agent, a compaction or a restart. rig queue handoff closes yours and opens the next agent's in one step, and a task that's waiting on something can carry a timer that wakes its agent. See Assign tasks to agents, Timers that wake your agents and Coordination.

rig ps --nodes shows each agent as working, idle, needs-input or unknown, with its queued work. rig parked names agents that stopped while they still have tasks, and rig tui shows the whole team live. When OpenRig can't tell what an agent is doing, it says unknown instead of guessing idle. See Live activity per agent, Find stalled tasks and The terminal UI.

An agent asks by creating a queue row addressed to you. With your own Slack app connected, the request posts to your channel with up to four answers as buttons, and your answer goes back to the agent that asked. Without Slack, requests still wait for you in the TUI's attention view. See Agents ask you for decisions and Slack app setup.

In 0.6.5, rig provider status shows how much of Claude's five-hour and weekly limits you've used and when they reset (it needs Claude Pro or Max; Codex reads as unknown). OpenRig doesn't pause queued work or switch accounts for you: work for a limited agent stays queued until the reset, or you reroute it with rig queue fallback. See See usage limits and resets and Auth and environment.

The queue, its wake timers and each agent's conversation are kept on disk. After a stop or a reboot, rig up <rig> restores the team from its newest snapshot and resumes each conversation, and it won't silently start a seat fresh if a conversation can't be resumed. Before a planned reboot, rig restore-check tells you whether each rig would come back. See Restore after a restart or reboot and Lifecycle.

Not as one rig, but agents on different machines can message each other, read each other's screens and hand each other queue work once you pair the machines. Each machine needs its own checkout and sign-ins, since OpenRig doesn't sync repositories or logins. Use a trusted private network such as Tailscale. See Agents across machines and fleets and the multiple machines guide.