From 572dba831d6d40e49955fc23d06456073dbbf5ef Mon Sep 17 00:00:00 2001 From: Mike Schwarz <171890339+mvschwarz@users.noreply.github.com> Date: Mon, 5 Oct 2026 20:47:22 -0700 Subject: [PATCH] docs: Node on Linux, the npm 11 install-scripts warning, and cmux on macOS only (#839) From a blank-machine install on Ubuntu 24.04: the README and getting-started now name a Linux route to a supported Node.js (nvm or NodeSource, since the distribution's own may be 18), say cmux is macOS-only and optional, and explain that npm 11 and later can skip the CLI's postinstall Node.js and SQLite check with an install-scripts warning, which is expected, and how to run that check directly. --- README.md | 6 ++++-- docs/reference/getting-started.md | 7 +++++-- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index d9d89d55b..33760864f 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ Not setting this up today? Get the next walkthrough and occasional OpenRig updat ## Install and first run -Requires Node.js 22 or 24 and tmux, on macOS or Linux. On a Mac with Apple silicon, use Node.js 22 ([compatibility history](docs/releases/v0.5.15.md#known-compatibility-limitation)). Native Windows is not supported yet, and WSL2 has not been tested. 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. +Requires Node.js 22 or 24 and tmux, on macOS or Linux. On Linux, the distribution's own Node.js can be older (Ubuntu 24.04's is 18); install a supported version with [nvm](https://github.com/nvm-sh/nvm) (`nvm install 22`) or NodeSource. On a Mac with Apple silicon, use Node.js 22 ([compatibility history](docs/releases/v0.5.15.md#known-compatibility-limitation)). Native Windows is not supported yet, and WSL2 has not been tested. 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. ```bash npm install -g @openrig/cli @@ -29,6 +29,8 @@ rig setup --dry-run To install with Bun instead, run `bun add -g @openrig/cli`. OpenRig still runs on Node.js, so install Node.js 22 as well. Bun may block this package's postinstall script, in which case the Node.js and SQLite check described under [what OpenRig changes on your machine](#what-openrig-changes-on-your-machine) does not run at install time. +npm 11 and later can skip that postinstall script and print `npm warn install-scripts` naming `@openrig/cli`. That's expected: the CLI still works, and only the Node.js and SQLite check was skipped. To run it yourself, use `node "$(npm root -g)/@openrig/cli/scripts/check-abi.mjs"`; `rig doctor` checks the Node.js version only. + Choose the working account you already have: **Claude Code, Codex, or both**. Reuse an explicit choice; no second subscription is required. `rig setup --dry-run` previews the broader setup, but applying `rig setup` checks both harnesses and installs a missing one, and on macOS cmux too. It is optional for the [selected-provider path](docs/reference/getting-started.md#choose-your-providers). Before launching, your agent asks once: **“Allow your agents to run OpenRig commands without repeated permission prompts?” Yes — recommended / No — keep prompts.** This covers every `rig` command, including starting/stopping agents and configuration, at personal project scope unless you explicitly choose user-wide sessions. It is not global YOLO or permission to invent work. On Yes, the agent [adds and verifies native rules](docs/reference/getting-started.md#have-your-agent-configure-permissions); No or no answer leaves settings unchanged. An existing explicit choice is reused. Say “Undo the OpenRig command allowances added by this setup” to remove only its additions. @@ -369,7 +371,7 @@ Optional: ## Setup and Troubleshooting -- `rig setup` attempts core machine preparation: tmux, cmux, Claude Code, Codex, and tmux defaults. It reports what it tried and what actually succeeded. If something fails, it gives the local agent enough context to finish the job. +- `rig setup` attempts core machine preparation: tmux, Claude Code, Codex and tmux defaults, plus cmux on macOS. cmux is optional and macOS-only; elsewhere setup skips it and `rig doctor` only warns that it's missing. It reports what it tried and what actually succeeded. If something fails, it gives the local agent enough context to finish the job. - `rig setup --full` attempts a broader operator workstation setup (jq, gh) on top of core. - `rig doctor` inspects current system health and helps diagnose problems after setup. Use it when something stops working or after machine changes. diff --git a/docs/reference/getting-started.md b/docs/reference/getting-started.md index c9ed5d9d4..35bb2a684 100644 --- a/docs/reference/getting-started.md +++ b/docs/reference/getting-started.md @@ -5,7 +5,10 @@ first-project recipes provide the same two seats: an outcome owner and an independent checker. Choose Claude Code, Codex, or one of each using the accounts you already have. Terminal-provider support does not change the harness or login. -You need Node.js 22 or 24 and tmux, on macOS or Linux. On a Mac with Apple +You need Node.js 22 or 24 and tmux, on macOS or Linux. On Linux, the +distribution's own Node.js can be older (Ubuntu 24.04's is 18); install a +supported version with [nvm](https://github.com/nvm-sh/nvm) (`nvm install 22`) +or NodeSource. On a Mac with Apple silicon, use Node.js 22 (see the [compatibility history](../releases/v0.5.15.md#known-compatibility-limitation)). Native Windows is not supported yet, and WSL2 has not been tested. Node 20 and @@ -88,7 +91,7 @@ command before proceeding. Confirm account access to any pin; if unavailable, ask for a supported model choice rather than silently substituting a model or provider. After launch, confirm the actual native model before assigning work. -Install OpenRig (`npm install -g @openrig/cli`) and check `tmux -V`. Check **only the selected providers**: +Install OpenRig (`npm install -g @openrig/cli`) and check `tmux -V`. With npm 11 or later, an `npm warn install-scripts` line for `@openrig/cli` is expected: only the postinstall Node.js and SQLite check was skipped, and `node "$(npm root -g)/@openrig/cli/scripts/check-abi.mjs"` runs it. Check **only the selected providers**: - Claude Code: `claude --version` and `claude auth status`. If sign-in is missing, ask once: “Please run `claude auth login` in your launch environment.”