OpenRig: Multi-Agent Systems That Hijack Your Terminal
Hook
OpenRig doesn't call AI APIs—it launches commercial CLI tools in tmux sessions and tricks them into thinking they're part of a coordinated team. It's either brilliantly pragmatic or a Rube Goldberg machine, depending on your tolerance for filesystem modifications.
Context
Most AI agent frameworks take the obvious path: wrap model APIs, manage authentication, handle rate limiting, build persistence. OpenRig takes a radically different approach—it treats Claude Code and GitHub Codex as black boxes, launching their official CLI tools in managed tmux sessions and orchestrating them through a Node.js daemon backed by SQLite.
This architecture exists because maintaining API integrations is a treadmill. Provider APIs change, authentication flows evolve, and permission systems get overhauled. Meanwhile, commercial coding tools like Claude Code and Codex already handle these concerns—they're authenticated, battle-tested, and receive ongoing updates. OpenRig's bet is that wrapping these CLIs as harness-managed agents lets you focus on coordination logic rather than infrastructure maintenance. The trade-off is fundamental: you inherit all the upstream CLI limitations and execution models, but you avoid rebuilding what already works. For teams already committed to these tools who need persistent, role-based agent workflows rather than one-off chat sessions, OpenRig materializes an operational model that's painful to achieve manually.
Technical Insight
OpenRig's architecture centers on a daemon that manages agent lifecycle through tmux session orchestration. When you define a rig (team) with pods (groups) and seats (individual agents), the daemon materializes this topology into tmux sessions, injecting environment variables that give each seat an identity and connection details:
# example-rig.yaml
name: backend-team
pods:
- name: feature-pod
seats:
- name: architect
provider: claude
role: "Design system architecture and review PRs"
skills:
- code-review
- system-design
- name: implementer
provider: codex
role: "Write implementation code based on architect's specs"
plugins:
- test-generator
When you launch this rig, the daemon creates tmux sessions for each seat and injects OPENRIG_SEAT_ID, OPENRIG_DAEMON_HOST, and workspace paths. The clever part is how skills and plugins get projected: OpenRig writes them to provider-specific locations (~/.claude/skills/ for Claude Code, .codex/plugins/ for Codex) so the underlying CLIs discover them as native capabilities:
// Simplified seat initialization
class SeatManager {
async launchSeat(seatConfig: SeatConfig): Promise<void> {
const workspace = await this.prepareWorkspace(seatConfig);
// Write trust configuration to skip permission prompts
await this.writeProviderTrust(seatConfig.provider, workspace);
// Project skills/plugins to provider locations
await this.projectCapabilities(seatConfig);
// Launch in tmux with injected environment
const env = {
OPENRIG_SEAT_ID: seatConfig.id,
OPENRIG_DAEMON_PORT: this.daemon.port,
WORKSPACE: workspace.path
};
await tmux.createSession(seatConfig.name, {
command: this.getProviderCLI(seatConfig.provider),
env
});
}
}
Inter-agent communication happens through a message queue backed by the daemon's SQLite database. Agents don't call each other directly—they post messages to queues that other seats consume. This async model enables actual task decomposition: the architect seat can analyze requirements, post a specification to the implementer's queue, and move on to other work while the implementer processes it.
The permission system is where OpenRig gets aggressive. During rig launch, it writes trust configurations to bypass native tool confirmations—adding workspace paths to .claude/allowed_workspaces, writing .codex/trust.json, and injecting tmux hooks. This creates a pre-authorized environment where agents can operate without human interruption, but it requires accepting that OpenRig will modify multiple filesystem locations:
# Modifications during first launch
~/.claude/skills/ # Skill definitions for Claude seats
~/.codex/plugins/ # Plugin code for Codex seats
~/.tmux.conf # Session management hooks
workspace/.gitignore # Excludes for OpenRig state
workspace/.openrig/ # Local seat metadata
The rigbundle system packages these configurations for distribution. A .rigbundle archive contains the YAML spec, all skills/plugins, and trust configurations, letting you share complete agent teams including their prompt engineering and tool definitions. This is powerful for reproducible setups—you can version-control and distribute entire multi-agent workflows as single artifacts.
Observability is intentionally minimal. The TUI (openrig-tui) connects to the daemon and shows seat states, message queues, and basic health, but you get zero insight into model reasoning, token usage, or tool call sequences. To debug why an agent stopped or made a strange decision, you're reading Claude Code or Codex logs separately. OpenRig treats the underlying providers as true black boxes—it orchestrates their lifecycle but doesn't instrument their internals.
Gotcha
The provider coupling is brittle in ways that matter for production use. OpenRig completely depends on Claude CLI and Codex CLI maintaining stable interfaces for authentication, permission models, and command-line arguments. When Claude updates their CLI to require new authentication flows or change how skills are discovered, OpenRig breaks until it's updated. There's no API contract here—you're coupled to tools that can change without notice.
The filesystem modifications are also concerning for teams with security requirements. During setup, OpenRig writes executable hooks, trust configurations, and skill definitions across multiple locations with no rollback mechanism. The installation documentation reads like a liability disclaimer, explicitly calling out 'what changes on your machine' in a way that suggests even the maintainers are nervous about it. If you're in an environment where filesystem changes require audit trails or approval workflows, OpenRig's aggressive pre-trust model is a non-starter. SQLite concurrency limits also surface quickly—documentation warns about reliability concerns on WSL2 and compatibility issues with Node 24 on Apple Silicon, which aren't theoretical edge cases but real deployments developers use daily.
Verdict
Use if: You're already committed to Claude Code or Codex for development work, need persistent multi-agent workflows with role-based task handoffs (not just chat sessions), want message-queue coordination for sustained repository work, and can accept filesystem modifications across provider config locations. OpenRig's wrapper architecture is pragmatic when you value avoiding API maintenance over having full execution control, and rigbundles provide real value for distributing reproducible agent teams. Skip if: You're on native Windows, need observability into agent decision-making and token usage, require audit trails for filesystem modifications, want guarantees around upgrade stability, or prefer API-first frameworks where you control the execution model directly. The 6700 stars indicate real users finding value, but the tight coupling to commercial CLIs, opacity around what gets written where, and SQLite scaling limits make this unsuitable for teams wanting transparent, production-grade agent infrastructure. Evaluate crewAI or AutoGen for API-first alternatives before accepting OpenRig's trade-offs.