You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit e5e7e30
Browse filesBrowse the repository at this point in the historyBrowse files
OpenRig agent (dev-guard)
committed
docs: bring installation and first use to the top of the README
Adapt the planning draft with prerequisite ordering, explicit response targets
and documentation-index wording. Preserve machine-effects and upgrade text.
Co-authored-by: OpenRig agent (dev-planner) <noreply@openrig.dev>
Copy file name to clipboardExpand all lines: README.md
+92-83Lines changed: 92 additions & 83 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,32 +4,56 @@ A harness wraps a model. A rig wraps your harnesses. Define your agent team in Y
4
4
5
5
OpenRig 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.
6
6
7
-
The terminal UI is the shared dashboard; the CLI drives work and coordination. The older web UI is in maintenance mode with best-effort support.
7
+
## Install and first run
8
8
9
-
Launching a rig writes provider hooks and workspace trust settings. Before
10
-
running the commands below, review [what OpenRig changes on your machine](#what-openrig-changes-on-your-machine)
11
-
and back up the relevant files.
9
+
Requires 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.
12
10
13
11
```bash
14
12
npm install -g @openrig/cli
15
13
rig setup --dry-run
14
+
```
15
+
16
+
Review 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.
17
+
18
+
Before launching, ask your agent to [configure your chosen permissions](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.
19
+
20
+
Check prerequisites in your launch shell:
21
+
22
+
```bash
23
+
tmux -V
24
+
codex --version
25
+
codex login status
26
+
```
27
+
28
+
Resolve missing tools or login before continuing. From your repository, inspect the plan before launching the two Codex seats, an owner and a checker:
29
+
30
+
```bash
16
31
cd /path/to/your/repository
32
+
rig up first-project --cwd . --plan
17
33
rig up first-project --cwd .
18
34
rig tui --shared
19
35
```
20
36
21
-
`first-project` has two native Codex seats: an owner and a checker. The kernel
22
-
provides separate operational support and a shared TUI terminal. Check
23
-
`codex login status` and inspect `rig up first-project --cwd . --plan`before
readiness, a useful task, a reviewed result, Herdr/cmux terminals and recovery.
26
-
Review setup's plan before applying `rig setup`: it checks both native
27
-
harnesses and cmux. This starter requires tmux and authenticated Codex; the
28
-
other harness and terminal provider are optional for its repository task.
37
+
The 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.
38
+
39
+
Check 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:
40
+
41
+
```bash
42
+
rig 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.'
43
+
rig queue list --destination dev-owner@first-project --limit 1000
44
+
```
29
45
30
-
Ask your agent to [configure your chosen permissions](docs/reference/getting-started.md#have-your-agent-configure-permissions):
31
-
keep prompts, remember selected commands, or deliberately choose broader access.
32
-
The agent handles the setup and verification; OpenRig's shipped defaults stay unchanged.
46
+
Sending 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](docs/reference/getting-started.md) covers readiness, a useful task, a reviewed result, Herdr/cmux terminals and recovery.
-**Releases:**[GitHub Releases](https://github.com/mvschwarz/openrig/releases) and npm `@openrig/cli`
55
+
56
+
We aim to acknowledge issues and pull requests within one day; see [CONTRIBUTING.md](CONTRIBUTING.md#what-to-expect-from-us) for review targets.
33
57
34
58
## What OpenRig changes on your machine
35
59
@@ -95,70 +119,6 @@ files before first use. Daemon/bootstrap writes are automatic and do not each
95
119
have an interactive preview; `rig setup --dry-run` does not preview every later
96
120
startup effect.
97
121
98
-
## First Run
99
-
100
-
Check readiness, then give the owner a bounded outcome from your repository:
101
-
102
-
```bash
103
-
rig ps --nodes --rig first-project
104
-
rig 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.'
105
-
rig queue list --destination dev-owner@first-project --limit 1000
106
-
```
107
-
108
-
Sending a message does not itself create a queue item; the owner records the task.
109
-
Read the final artifact and the review of its exact candidate. Return to the
110
-
same owner for the next change. To leave the shared dashboard without stopping
111
-
it, press Ctrl-b then d; `rig tui --shared` returns to that view. Plain `rig tui`
112
-
opens an independent view. Closing a viewing terminal does not mean you should
113
-
relaunch the team.
114
-
115
-
## Upgrading an existing instance
116
-
117
-
For an existing installation, follow the [upgrade procedure](skills/_canonical/core/openrig-upgrade/SKILL.md) and the [0.5.14 release notes](docs/releases/v0.5.14.md). Preserve live seats during the upgrade; `rig down` is not an upgrade step.
118
-
119
-
### Crossing the 0.5.9 layout boundary
120
-
121
-
The migration below still applies when upgrading from a pre-0.5.9 instance.
122
-
123
-
0.5.9 makes `$OPENRIG_HOME/context` the addressable context library, writes
124
-
Claude telemetry to `state/context-usage` (and provider telemetry to
125
-
`state/provider-usage`), and installs the default System World at
126
-
`context/system/system-world.yaml`. Existing instances cross this boundary by
127
-
an **Agent-Operated Migration** from the shipped `openrig-upgrade` skill. The
128
-
target runtime reads canonical-first with legacy-fallback while new writes use
129
-
the canonical roots; a custom context-library root stays stable during
130
-
activation. This is not a directory rename to do while an old collector writes.
131
-
132
-
```bash
133
-
# SKILL_DIR is the installed openrig-upgrade skill directory.
`--help` prints the phase grammar without inventorying the instance. No phase
149
-
flag intentionally runs the read-only plan; unknown options fail nonzero before
150
-
plan or mutation.
151
-
152
-
Every phase emits JSON. Stop on any issue or incomplete receipt and follow its
153
-
`next` action; do not continue from copied legacy telemetry or retry a partial
154
-
mutation blindly. Preparation leaves legacy state and collector settings in
155
-
place. Verification accepts exact tail bytes only when that same seat has newer
156
-
paired context and provider samples under `state/`; finalization revalidates the
157
-
accepted tails, copies the library without overwrite, and switches config last.
158
-
The helper never removes the legacy telemetry or library. Retirement follows
159
-
separate stable runtime, writer, reader, and recovery proof. Daemon, database,
160
-
seat, plugin, and release lifecycle actions remain agent-owned.
161
-
162
122
## What It Does
163
123
164
124
OpenRig 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.
@@ -204,7 +164,7 @@ rig specs ls
204
164
205
165
## How It Works
206
166
207
-
OpenRig is a local daemon + CLI + terminal UI + MCP server, built on tmux. The older React web UI remains in maintenance mode.
167
+
OpenRig 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.
208
168
209
169
```
210
170
CLI / TUI / MCP
@@ -260,6 +220,53 @@ rig send vault-specialist@secrets-manager "Check Vault health and report status.
260
220
261
221
Requires Docker for service-backed rigs.
262
222
223
+
## Upgrading an existing instance
224
+
225
+
For an existing installation, follow the [upgrade procedure](skills/_canonical/core/openrig-upgrade/SKILL.md) and the [0.5.14 release notes](docs/releases/v0.5.14.md). Preserve live seats during the upgrade; `rig down` is not an upgrade step.
226
+
227
+
### Crossing the 0.5.9 layout boundary
228
+
229
+
The migration below still applies when upgrading from a pre-0.5.9 instance.
230
+
231
+
0.5.9 makes `$OPENRIG_HOME/context` the addressable context library, writes
232
+
Claude telemetry to `state/context-usage` (and provider telemetry to
233
+
`state/provider-usage`), and installs the default System World at
234
+
`context/system/system-world.yaml`. Existing instances cross this boundary by
235
+
an **Agent-Operated Migration** from the shipped `openrig-upgrade` skill. The
236
+
target runtime reads canonical-first with legacy-fallback while new writes use
237
+
the canonical roots; a custom context-library root stays stable during
238
+
activation. This is not a directory rename to do while an old collector writes.
239
+
240
+
```bash
241
+
# SKILL_DIR is the installed openrig-upgrade skill directory.
0 commit comments