OpenRig for VS Code

An unofficial extension that launches a persistent builder/reviewer team for your project, with an OpenRig sidebar and interactive agent tabs inside VS Code.

Install and start your first team

Requires VS Code 1.145 or later on Windows with WSL2, Linux, or Remote WSL. macOS is not supported in this release. Automatic Linux prerequisite installation requires an apt-based distribution.

1. Install OpenRig-VSC by ShaneDaly from VS Code's Extensions view, or use Extensions: Install from VSIX with the release package. Reload VS Code if prompted.
2. Open a project folder and trust the workspace.
3. Select OpenRig in the activity bar and click Check Environment. This only inspects requirements.
4. If anything is missing, choose Set Up OpenRig. Review any WSL confirmation and complete sudo or provider sign-in prompts. Setup starts no agents.
5. When the environment is ready, click Launch Team. The project rig opens in a Herdr editor tab inside VS Code. Individual agent tabs and the local dashboard remain available.
6. After reopening this workspace, use Reconnect to Team to attach to its running sessions without setup.

The default team uses Codex for both builder and reviewer. To use Claude or a mixed team, select openrig.providers in Settings before setup and launch. Provider sign-in takes place in the Linux terminal, even if you already signed in on Windows.

Accounts, costs, and project access

You need an account/subscription or API credentials accepted by your selected provider CLI. Provider usage may incur charges under your provider's plan; running two agents can consume more usage than a single session. Closing VS Code leaves agents running. Use Stop team to end this project's sessions.

Agents work in the trusted project and can read or change its files and run commands according to the provider and OpenRig permissions. Review their prompts and changes. Setup can install missing tools in Linux and change provider/OpenRig configuration; launch can add managed project guidance and hooks.

The extension does not implement its own telemetry or store provider credentials in its saved session metadata. Provider CLIs handle authentication and communicate with their services under their own data policies. Saved metadata includes project paths, team identity, distribution and provider choices. Diagnostic output can include local paths and CLI messages; redact secrets before sharing it.

Separate check, setup, launch, and reconnect actions

On Windows, detection reads canonical names from wsl --list --quiet and matches them to version/default information from wsl --list --verbose. Names with spaces and localized state labels are supported. The default development distribution is reused, preferring WSL2; Docker-managed distributions are excluded. An inconsistent or failed listing stops with manual recovery instructions. There is no fallback from a failed probe to an empty registry and then installation. If WSL itself cannot be queried, resolve that Windows error or install WSL manually, then check again.

Only Set Up OpenRig can install a distribution. When a successful query confirms no development distributions are installed (including when only Docker-managed distributions exist), a modal confirmation names Ubuntu (or the explicitly selected distribution), explains possible administrator access and reboot, and offers Install or cancellation. Docker-managed distributions are never used or modified. Declining performs no installation. WSL1 conversion likewise requires setup and a Convert confirmation. Check Environment, Launch Team and Reconnect never initiate installation or conversion.

Checking an existing distribution may start its WSL virtual machine to inspect Linux tools. Connection checks allow a minute for startup and retry a timeout once. Existing connection errors retain their cause rather than claiming a Linux account is missing. Newly installed distributions can open an initialization tab if first boot needs input. If Windows requests a restart, reopen the project afterward and choose setup again; the extension never reboots Windows itself.

During setup, inside Linux the extension:

• Checks curl, Git and tmux individually and installs only missing packages with apt.
• Preserves a working Linux Node.js 22 or 24, including system and user-managed installations. If needed, reuses an installed nvm version before downloading Node.js 24. Windows Node is not used.
• Installs a missing @openrig/cli with npm, using a user prefix when the system prefix is not writable.
• Checks for Herdr in the current PATH and its installation directory. Reuses an existing binary, or downloads and runs the official Herdr installer only when missing. An existing broken binary is reported instead of overwritten.
• Reuses existing provider CLIs and valid sign-in. Installs only missing selected providers, then runs rig setup --providers <choice> once to verify/configure OpenRig. Existing broken CLIs are reported instead of silently reinstalled.

During launch, it:

• Probes daemon health and reuses an already-running healthy instance. Starts it only when confirmed stopped, then verifies health. An already-running start exit code during a concurrent launch is accepted only after another successful health probe.
• Launches a team using OpenRig's maintained implementer and QA role definitions.
• Validates the generated spec with rig spec validate before launch. Agent references use paths relative to the spec, as required by OpenRig.
• Opens a standalone dashboard inside a VS Code editor terminal, so a stopped pre-existing kernel does not block it. Selecting an agent opens its live tmux session in another editor terminal using rig terminal attach.
• Opens Herdr in a VS Code editor terminal, waits for the exact control socket reported by the daemon, then populates this project's view using rig terminal open <project-team> --provider herdr --json. Reopening or reconnecting focuses the existing project tab instead of creating duplicates. A failed or partial view is reported instead of claiming the rig opened successfully. Your agents remain running if opening Herdr fails.

The default is two Codex agents. With both, the builder uses Claude and the reviewer uses Codex. Each workspace gets a stable team name derived from its Linux path and distribution. An already-live team is reused; a stopped team is restored with rig up --existing. Starting a team can require trust or permission responses; the sidebar shows the actual agent state and makes those terminals available during startup.

Setup scripts, progress markers and the generated rig spec live in VS Code's extension storage, outside the project. OpenRig itself manages guidance in the project and provider configuration in your Linux home. Upstream documents those changes, including Codex hooks/trust, Claude settings, discovery skills, tmux configuration, and the kernel's permission defaults: OpenRig setup and machine changes.

Settings

Settings affect new launches. An existing team's saved provider choices are preserved when restoring it. Stop and reconfigure that team's spec if you need to change its runtimes.

Controls and lifecycle

• Check Environment inspects requirements without installation or configuration.
• Set Up OpenRig installs/configures requirements without starting a team.
• Launch Team starts or restores this project's agents after a successful check.
• Reconnect to Team attaches to the saved running team without setup.
• Open Herdr opens or focuses this project's Herdr editor tab, or retries opening it after a failure.
• Open in external window is an optional sidebar action (also available as OpenRig: Open Herdr in External Window in the Command Palette). On Windows it opens Windows Terminal running Linux Herdr in the selected WSL distribution; native Linux uses an available desktop terminal.
• Setup output reveals the interactive setup/dashboard tab, or the extension's diagnostic output if the tab is closed.
• Refresh reads the current inventory from OpenRig.
• Select an agent to attach to its live terminal. Repeated clicks reuse its tab.
• Stop team runs rig down <this-project-team>; it does not stop other teams or the shared daemon.

Closing VS Code or a terminal detaches from the agents. They keep running in tmux until stopped. Project/team identity, Linux distribution and provider choices are persisted in VS Code workspace state and an atomic per-workspace metadata file in extension storage. Reopening the same workspace restores a Reconnect action without running any processes automatically. Metadata is saved only after the launch script confirms team startup; a failed launch preserves the previous saved session. A Herdr failure does not discard a successfully launched team. Reconnect recreates its Herdr support files from the installed extension when opening the view. Only validated metadata is saved, never credentials or auth output; metadata for other projects/platforms is ignored. Provider sign-in happens within Linux and is handled by the CLI, not the webview. OpenRig may create managed project guidance and provider hooks when starting agents; these inherent startup changes are separate from running extension setup.

Requirements and limits

• Windows supporting WSL2, or Linux / a Remote WSL extension host; VS Code 1.145 or later.
• Internet for first installation and a provider account/subscription or API setup accepted by its CLI.
• apt-based Linux for automatic prerequisite installation. On other Linux distributions, install the listed prerequisites using your package manager first.
• The default Herdr editor tab needs no external terminal application or desktop display. The optional external action requires Windows Terminal on Windows/WSL, or a desktop display and GNOME Terminal, Konsole, Ghostty or xterm on native Linux.
• The project and extension storage must be accessible from Linux. Mapped Windows drives may need mounting in WSL. Opening the project in a Remote WSL window is also supported.
• macOS and virtual workspaces are not supported by this version.
• Integration targets the current OpenRig CLI and its shipped daemon/specs/agents/development layout; older versions may require updating OpenRig. Existing CLI installations are not silently upgraded.

Troubleshooting and reporting problems

Report bugs and request features on the GitHub issue tracker. For a useful problem report, include the extension and VS Code versions, Windows/Linux version, WSL distribution if applicable, selected provider, the action that failed, and relevant Setup output. Remove tokens, private project content and other sensitive details.

If setup fails, inspect Setup output, resolve the issue, then check or retry setup as appropriate. Windows installation/reboot handling is based on Microsoft's WSL commands.

Development and verification

npm install
# Press F5 to open an Extension Development Host for local development.
npm run check
npm run test:integration
npm run package

check runs ESLint, JavaScript type checking and Node tests. Tests cover platform detection, path quoting, workspace trust, installation errors, startup inventory, attachment validation, stop scope, and the actual Bash bootstrap with fake installation/provider/daemon commands. Bash is discovered from the OS or Git for Windows; set OPENRIG_TEST_BASH if needed.

test:integration normally runs the command-registration smoke test in an isolated VS Code Extension Development Host. The ordinary automated checks do not install WSL, download Linux tools, authenticate providers, or start real agents.

To opt into a live test, select a disposable project with an already prepared environment. The suite verifies read-only checking, launches/reuses the team twice, and checks that reconnect reuses the same agents and Herdr tab without setup:

$env:OPENRIG_LIVE_TEST_PROJECT = 'C:\path\to\test-project'
npm run test:integration
Remove-Item Env:\OPENRIG_LIVE_TEST_PROJECT

This live test opens Herdr in a real VS Code editor terminal and leaves the team running. On a subsequent run, set OPENRIG_EXPECT_RESTORE=1 to verify saved-session recovery in a fresh extension host. These flows are tested against the existing OpenRig WSL distribution with signed-in Codex. First-time installation on a fresh Windows machine remains a separate manual check.

Publishing

Marketplace publishing uses GitHub Actions trusted publishing, without a personal access token. Configure this policy under the ShaneDaly publisher's Trusted Publishing page:

Commit and push the release changes, including .github/workflows/publish.yaml, to master. On GitHub, open Actions → Publish extension → Run workflow, select master, and run it. The workflow installs locked dependencies, runs lint, type checking and unit tests, packages the extension, and publishes that VSIX using OIDC. It runs only when manually requested on master.

For subsequent releases, update the version in package.json and package-lock.json and add release notes to CHANGELOG.md before running the workflow. Marketplace versions cannot be overwritten.

Source and license

Source code and contributions: ShanedalyCS/openrig-vsc.

Copyright (c) 2026 Shane Daly. This extension is available under the MIT License. OpenRig, Herdr, and provider CLIs are separate projects with their own licenses and service terms.