OpenRig Command Cheat Sheet

OpenRig provides a command-line interface for managing coding agents, development teams, tasks, and terminal sessions.

Whether you’re running OpenRig on Ubuntu, working with Codex or Claude Code, or managing multiple AI coding agents, knowing a few essential commands makes the system much easier to operate.

This cheat sheet covers installation checks, starting and stopping OpenRig, managing agent teams, sending instructions, monitoring tasks, and troubleshooting common problems.

Compatibility: OpenRig 0.7.10 (November 2026). Commands and flags may change between releases. Run rig --help or rig <command> --help to check your installed version.

1. OpenRig Quick Reference

These are the commands you’ll probably use most often.

Note: The built-in starter team uses Claude Code and Codex by default. If you’ve installed only one provider, ask OpenRig’s operator to adapt the team before launching it.

2. Installation and Setup Commands

Use these commands to check your installation and configure a coding provider.

OpenRig normally installs Herdr TUI during setup. If you prefer plain tmux, add --no-herdr to the setup command.

For example:

rig setup --providers codex --no-herdr

rig setup --providers codex --no-herdr

3. Starting and Stopping OpenRig

The OpenRig daemon maintains the coordination state for agents and teams.

Start OpenRig

rig daemon start

rig daemon start

To bind the daemon explicitly to localhost on port 7433:

rig daemon start \
  --host 127.0.0.1 \
  --port 7433

rig daemon start \
  --host 127.0.0.1 \
  --port 7433

By default, a new daemon startup also starts OpenRig’s kernel team, including its operator.

To start without the kernel:

rig daemon start --no-kernel

rig daemon start --no-kernel

The kernel is useful for guided team creation. The --no-kernel option is more appropriate when you intend to launch a predefined team yourself.

Daemon command reference

Stopping the daemon does not automatically stop agent sessions.

If you want to shut everything down, inspect the running rigs, stop the project teams, stop kernel last if it is running, and then stop the daemon.

rig ps --json

rig down starter
rig down kernel
rig daemon stop

rig ps --json

rig down starter
rig down kernel
rig daemon stop

Only run rig down for rigs that actually exist. Stopping the kernel also ends the operator’s session.

4. Viewing Agents and Running Teams

OpenRig includes commands for inspecting active teams and individual agents.

Find an agent’s terminal session

When connected over SSH, use:

rig ps --nodes --rig starter --json \
  --fields logicalId,canonicalSessionName,tmuxAttachCommand

rig ps --nodes --rig starter --json \
  --fields logicalId,canonicalSessionName,tmuxAttachCommand

The output includes the session name and attachment command for each agent.

Copy the reported tmuxAttachCommand into your terminal to connect to the agent.

This is particularly useful on headless Ubuntu servers.

Useful tmux keyboard shortcuts

When attached to an agent session, these tmux shortcuts are helpful:

Detach from an agent session when you want to return to your normal shell without interrupting the agent.

5. Starting and Managing Agent Teams

A group of coding agents managed by OpenRig is called a rig.

Preview a starter team.

From a project directory:

rig up starter --cwd . --plan

rig up starter --cwd . --plan

The --plan flag previews the launch without starting the team.

Start the starter team

rig up starter --cwd .

rig up starter --cwd .

If your team has a custom YAML configuration, use its file path:

rig up ./rig.yaml --plan

rig up ./rig.yaml

rig up ./rig.yaml --plan

rig up ./rig.yaml

Team management commands

Replace starter with your rig’s actual name when using a custom configuration.

6. Communicating With Coding Agents

OpenRig lets you send instructions directly to an agent without manually switching terminal sessions.

Send a message

rig send dev-build@starter \
  "Please review the website's current HTML structure."

rig send dev-build@starter \
  "Please review the website's current HTML structure."

This targets the builder seat in the starter rig.

Ask an agent for a status update

rig send dev-build@starter \
  "Summarise your progress and any outstanding issues."

rig send dev-build@starter \
  "Summarise your progress and any outstanding issues."

Request a review

rig send dev-review@starter \
  "Review the latest changes for bugs and regressions."

rig send dev-review@starter \
  "Review the latest changes for bugs and regressions."

The exact agent addresses depend on the team configuration. Find them with:

rig ps --nodes --rig starter

rig ps --nodes --rig starter

Other communication commands

A message sent using rig send is not automatically a formal tracked task. Use the queue commands below when work needs a persistent task record.

7. Managing Tasks and Queued Work

OpenRig includes a queue system to record, assign, and track work.

List work assigned to an agent

rig queue list \
  --destination dev-build@starter

rig queue list \
  --destination dev-build@starter

Create a tracked task

rig queue create \
  --destination dev-build@starter \
  --summary "Improve website navigation" \
  --body "Review the navigation and implement the agreed accessibility changes."

rig queue create \
  --destination dev-build@starter \
  --summary "Improve website navigation" \
  --body "Review the navigation and implement the agreed accessibility changes."

The command returns a task identifier.

Use that identifier when inspecting the task.

Task management reference

For small tasks, a direct instruction may be sufficient. Use the queue when you need an assignment, recorded state, and a work history.

8. Validating Team Configuration Files

Advanced OpenRig configurations use YAML files to define teams and agent profiles.

Before launching a custom team, validate its configuration.

Validate an agent definition

rig agent validate ./agents/worker/agent.yaml

rig agent validate ./agents/worker/agent.yaml

Validate a rig specification

rig spec validate ./rig.yaml

rig spec validate ./rig.yaml

Run a preflight check

rig spec preflight ./rig.yaml

rig spec preflight ./rig.yaml

Preview the launch

rig up ./rig.yaml --plan

rig up ./rig.yaml --plan

These checks help diagnose invalid YAML structure, unresolved references, or missing startup files.

Validation and preflight have different purposes. A syntactically valid specification does not guarantee that the selected coding provider can authenticate or that every seat will launch successfully.

9. Troubleshooting and Diagnostics

If OpenRig behaves unexpectedly, start with the status and diagnostic commands.

When an agent stops during startup

OpenRig may report a partial launch when an agent waits for authentication, a workspace-trust decision, or a permission prompt.

Inspect the existing agent terminal, answer the prompt, and use the continuation command OpenRig shows.

The general form is:

rig seat continue <seat>

rig seat continue <seat>

Use the actual seat address from the startup message.

When the SQLite database produces an ownership warning

If OpenRig reports that it could not verify who owns its SQLite database, inspect the running processes before making changes.

For a default installation under a rigdev account:

pgrep -af 'openrig|rig.*daemon'

timeout 10s lsof -nP -- \
  /home/rigdev/.openrig/openrig.sqlite

pgrep -af 'openrig|rig.*daemon'

timeout 10s lsof -nP -- \
  /home/rigdev/.openrig/openrig.sqlite

An lsof result showing the expected daemon PID confirms that the process has the file open. It does not prove that another process never accessed it.

Do not delete the SQLite database or its journal files to clear a warning.

10. Monitoring Usage

OpenRig includes commands for inspecting usage and cost-related information.

Usage data depends on the providers and information available to OpenRig. Treat it as operational visibility rather than a guaranteed reconciliation with the provider’s bill.

11. Useful JSON Commands

Many OpenRig commands support --json, which is convenient when using shell scripts or jq.

For example:

rig status --json

rig status --json

Check the running agents in JSON format:

rig ps --nodes --json

rig ps --nodes --json

Inspect queued work:

rig queue list --json

rig queue list --json

JSON is useful for automating reporting, but the fields vary between commands and releases. Inspect the returned structure before writing scripts that depend on it.

12. Example: A Typical OpenRig Development Session

Here’s a simple command sequence for working on a website.

Check the installation

rig --version
rig doctor

rig --version
rig doctor

Start the daemon

rig daemon start
rig status

rig daemon start
rig status

Navigate to your project

cd ~/projects/my-first-website

cd ~/projects/my-first-website

Preview the team

rig up starter --cwd . --plan

rig up starter --cwd . --plan

If you have the required providers configured, start the team:

rig up starter --cwd .

rig up starter --cwd .

Inspect the agents

rig ps --nodes --rig starter

rig ps --nodes --rig starter

Assign a task

rig send dev-build@starter \
  "Improve the website's responsive layout and ask the reviewer to inspect the changes."

rig send dev-build@starter \
  "Improve the website's responsive layout and ask the reviewer to inspect the changes."

Monitor the work

rig queue list --destination dev-build@starter

rig ps --nodes --rig starter

rig queue list --destination dev-build@starter

rig ps --nodes --rig starter

Review the source changes

From the project directory:

git status --short
git diff --check
git diff

git status --short
git diff --check
git diff

Review and test changes before approving a commit or deployment.

Stop the team

rig down starter

rig down starter

Stop the daemon when you no longer need it:

rig daemon stop

rig daemon stop

If the kernel is running and you want a complete shutdown, stop it after your project rigs and before stopping the daemon.

13. Commands and Practices to Remember

A few operating rules will prevent common mistakes:

1. Check before launching. Use rig up ... --plan to inspect what OpenRig intends to start.
2. Inspect agent readiness. A running daemon does not guarantee all agents are ready.
3. Know the session addresses. Use rig ps --nodes before sending commands to a named agent.
4. Understand shutdown behavior. rig daemon stop Leaves agent sessions running; rig down stops the selected rig.
5. Protect project credentials. Avoid giving agent accounts unnecessary access to production systems.
6. Review code before deployment. A completed agent task is not the same as a tested release.

Official OpenRig Documentation

For command flags, new features, and version-specific behavior, consult the project’s official documentation:

• OpenRig documentation
• OpenRig CLI reference
• Complete command reference
• OpenRig GitHub repository
• OpenRig release history

The installed CLI is the final authority on supported options:

rig --help
rig <command> --help

rig --help
rig <command> --help

Final tip: Start with rig status, rig ps, rig tui, rig send and rig down. Those commands cover most everyday interactions with a running OpenRig team. Add the queue, configuration, and diagnostic commands as your projects become more complex.