RunSystem Helper

rshelper signs in to RunSystem, detects and configures both Claude Code and OpenAI Codex, and reports current all-model and model-group quotas.

Quick start

Install Node.js 18 or later, plus at least one supported coding CLI:

• Claude Code
• Codex CLI

Then install and run the helper:

npm install --global rshelper
rshelper

Without a global install:

npx --yes rshelper

The guided setup detects claude and codex, opens browser sign-in, stores a personal RunSystem key under ~/.runsystem, backs up both tools' existing user configuration, and configures RunSystem. Missing CLIs do not block setup: their configuration is prepared for a later installation. If Claude Code is present, the helper also installs the bundled account slash-command plugin.

Restart the configured tools, then launch them normally:

claude
codex

Claude Code can select RunSystem aliases with /model. Codex starts with the Responses-compatible RunSystem model selected during setup.

Commands

rshelper                 # Interactive account menu
rshelper setup           # Guided setup
rshelper detect          # Detect Claude Code and Codex
rshelper login           # Sign in and configure both tools
rshelper configure       # Refresh models and both configurations
rshelper configure --tool claude # Configure only Claude Code
rshelper configure --tool codex  # Configure only Codex
rshelper usage           # Show all-model and model-group quota windows
rshelper status          # Show account, CLI, model, and backup status
rshelper restore         # Restore both tools' original provider settings
rshelper restore --tool claude   # Restore only Claude Code
rshelper restore --tool codex    # Restore only Codex
rshelper logout          # Restore, remove local credentials, and sign out
rshelper install-plugin  # Install/update the Claude Code account plugin

The legacy runsystem-claude-code-helper and runsystem-coding-helper executables remain as compatibility aliases. The preferred commands are rshelper and runsystem-helper.

Configuration and credentials

The helper manages only RunSystem-related fields and retains backups under ~/.runsystem/backups:

• Claude Code: ~/.claude/settings.json
• Codex: ${CODEX_HOME:-~/.codex}/config.toml

Codex is configured with a runsystem custom provider, the Responses wire API, and <RunSystem base URL>/v1. Both tools use a command-backed credential helper; the API key is not embedded in JSON or TOML. New credentials live at ~/.runsystem/api-key; legacy ~/.runsystem/claude-code-api-key credentials remain readable for migration.

Set CLAUDE_CODE_BIN or CODEX_BIN to an executable path when a CLI is not on PATH. Set CODEX_HOME to use a non-default Codex state directory. Absolute Node/executable paths and argument arrays are used for credential helpers so paths containing spaces work on Linux, Windows x86-64, and Apple Silicon macOS.

restore removes the helper-managed settings and restores provider/model values that existed before setup while retaining unrelated later edits. Backups are kept so setup can be safely repeated.

The interactive menu exposes the same per-tool actions. The stored RunSystem credential is shared, but each tool gets its own command-backed credential and provider configuration. Restoring one tool restores its previous credential helper/provider fields without changing the other tool or deleting the shared RunSystem account key.

Windows joined-domain users

On Windows, npm's "global" install is global to the current Windows account, not to every account on the computer. If npm is run as another administrator, rshelper.cmd is created under that administrator's npm prefix and the signed-in domain user cannot find it. Install from a non-elevated PowerShell window opened as the domain user who will run the helper.

If installation succeeds but rshelper is not found, compare the active prefix and command lookup:

npm config get prefix
Get-Command rshelper -ErrorAction SilentlyContinue

For managed/domain machines, a stable per-user prefix under Local AppData avoids both another account's profile and a roaming AppData policy. Run this as the intended non-elevated user:

$npmUserPrefix = Join-Path $env:LOCALAPPDATA "npm"
npm config set prefix $npmUserPrefix --location=user
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
$pathEntries = @($userPath -split ";" | Where-Object { $_ })
if ($pathEntries -notcontains $npmUserPrefix) {
  [Environment]::SetEnvironmentVariable("Path", (($pathEntries + $npmUserPrefix) -join ";"), "User")
}
$env:Path = "$npmUserPrefix;$env:Path"
npm install --global rshelper
rshelper

The post-install message prints the exact account, npm prefix, and launcher path used by npm. Group Policy can overwrite the user PATH; in that case an administrator must allow the per-user prefix, or the user can run npx --yes rshelper without relying on the global shim.

Usage and quota precedence

rshelper usage and Claude Code's /runsystem-account:usage query live data from both /me/usage and /me/model-groups. The report preserves the existing all-model 5-hour and weekly windows and adds each model group's corresponding windows and member models. A model-specific or model-group quota is more specific and therefore takes priority over the all-model fallback for requests to models in that scope.

The Claude Code plugin also provides:

/runsystem-account:usage
/runsystem-account:feedback

Local development

npm install
node ./bin/runsystem-helper.mjs detect
node ./bin/runsystem-helper.mjs
npm test
npm run validate

The npm package is platform-neutral and requires Node.js 18+. All filesystem paths use Node's cross-platform APIs; Windows CLI shims are launched through the Windows shell, while Linux and macOS use direct process spawning.

Standalone platform bundles

npm run bundle:platforms uses Bun's compile mode to cross-build standalone archives that do not require Node.js for the main helper:

• linux-x64 via bun-linux-x64-baseline
• windows-x64 via bun-windows-x64-baseline
• darwin-arm64 via bun-darwin-arm64 (Apple M-series)

Artifacts are written under dist/platform/runsystem-helper-<version>-<target>/ and archived as .tar.gz (Linux/macOS) or .zip (Windows), with SHA-256 values in SHA256SUMS. Each folder contains runsystem-helper (runsystem-helper.exe on Windows), license and install files, and the adjacent Claude plugin files needed by install-plugin.

Bun can cross-compile all three targets from one host. tar and zip must be available to create the archives.

Release validation

npm run validate
npm run bundle:platforms

validate runs the Node test suite and npm pack --dry-run. The bundle command recreates the platform output and verifies that source maps are not packaged.