Installing HarnessLink

HarnessLink is the controller for your coding agents — it routes their model calls, gives them shared memory, banks what they do, and syncs and restores your setup. You code in omp, Claude Code, Codex or pi. HarnessLink was called SuperPi until October 2026; the command is still superpi (see RENAME.md).

This guide covers a completely fresh machine through to the HarnessLink service running with your harnesses wired into it.

No GitHub account, token or git is needed, and nothing is compiled: the installer fetches the source tarball from harnesslink.sh and installs its production dependencies with Bun.

Alpine (musl). The installer adds bun's libstdc++ and libgcc via apk. The npm omp package ships only glibc natives, so on musl omp comes from the upstream omp-linux-musl-<arch> release binary instead, checked against the release's SHA256SUMS.txt. omp update keeps using the musl asset.

The installer also installs omp (@oh-my-pi/pi-coding-agent, upstream oh-my-pi) — a harness to code in — and links it beside superpi. Pass --no-omp to skip that; Claude Code, Codex and pi work just as well.

irm https://harnesslink.sh/install.ps1 | iex

The PowerShell one-liner downloads and runs install.ps1 from harnesslink.sh. Open PowerShell and paste it.

Prerequisites

The installer downloads the source tarball from https://harnesslink.sh/superpi-src.tar.gz, extracts it with the tar.exe that ships with Windows 10+ and installs its production dependencies with Bun. No git, GitHub or compiler involved.

Installer parameters. irm … | iex cannot pass parameters. To pass them, download the script and run it as a file:

irm https://harnesslink.sh/install.ps1 -OutFile install.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -Yes

There is no --with or --cloud equivalent on Windows. Install other harnesses afterwards with superpi harness install <id>, and run superpi cloud setup yourself after a -Yes install.

Troubleshooting — Windows

irm blocked by execution policy The default Windows policy may block running scripts downloaded from the internet. Bypass it for the current shell only (it is not a system-wide change):

Set-ExecutionPolicy -Scope Process Bypass
irm https://harnesslink.sh/install.ps1 | iex

superpi: command not found / superpi.cmd not recognised Bun's bin directory (%USERPROFILE%\.bun\bin) is not on PATH. Add it permanently in System Settings → Environment Variables, or for the current session:

$env:PATH = "$env:USERPROFILE\.bun\bin;$env:PATH"

Bun install fails behind a proxy Set HTTPS_PROXY before running the installer:

$env:HTTPS_PROXY = 'http://proxy.corp.example.com:8080'
irm https://harnesslink.sh/install.ps1 | iex

Environment variables for custom installs

$env:SUPERPI_DIR  = 'D:\dev\superpi-src'   # where to put the source
$env:SUPERPI_SITE = 'https://harnesslink.sh'  # tarball + installer base URL
irm https://harnesslink.sh/install.ps1 | iex

curl -fsSL https://harnesslink.sh/install.sh | bash

harnesslink.sh serves the repository's install.sh verbatim; it is the only source and needs no authentication.

From 17.5.55 the installer (and superpi update) also links harnesslink and hlk to the same command; hlk is skipped if another program already owns that name. All three behave identically, and this guide uses superpi. On Windows they are superpi.cmd, harnesslink.cmd and hlk.cmd.

bash install.sh --help

  --dir <path>     Source location (default: ~/.superpi-src)
  --no-omp         Skip installing omp (a harness to code in)
  --with=<ids>     Also install the listed harnesses after omp (comma-separated)
                     Valid ids: omp claude-code codex gemini pi dsh
                     Example: --with=claude-code,codex
  --cloud          Run the onboarding even with --yes (it still needs a
                     terminal: sign-in happens in your browser)
  --yes            Assume yes for anything that modifies the system

The installer is re-runnable: every step checks before acting, so running it again updates rather than reinstalls.

If you would rather see each step:

mkdir -p ~/.superpi-src && curl -fsSL https://harnesslink.sh/superpi-src.tar.gz | tar -xz -C ~/.superpi-src
cd ~/.superpi-src
bun install --production
sh scripts/link-superpi.sh    # links superpi (plus harnesslink and hlk) into ~/.bun/bin
bun install -g @oh-my-pi/pi-coding-agent   # omp, a harness to code in

superpi --version
superpi --smoke-test
superpi                       # the home screen: service, sign-in, sync, each harness's wiring

--smoke-test loads every command and exercises the gateway and the MCP relay end to end in a throwaway directory, so a broken install fails here rather than on first use.

An interactive install ends by opening superpi cloud setup directly (no extra question: its first screen is the confirmation). --yes, CI and other headless runs skip it and print Finish setup: superpi cloud setup instead. Run it any time:

superpi cloud setup       # the onboarding: plan → sign in → everything else automatic
superpi cloud status      # sync health afterwards
superpi gateway status    # gateway + cloud sync health

1. Plan. One screen lists everything that turns on — all of it on by

   default: sign in, cloud sync, the HarnessLink service, then each harness found on this machine with the features it supports here, then restoring from the cloud (sessions, history, memories, harness setup) and importing old memories. Per-harness features and where each applies:

   Feature	What it does	Harnesses
   Gateway routing	model calls go through the local gateway	Claude Code, Codex, omp, pi
   Transcript sync	session transcripts, prompt history and the harness's own memory files upload	every harness with an adapter: Claude Code, Codex, omp, pi, Cursor, Antigravity (see MULTI_HARNESS.md for what each one actually yields)
   Autobank	every finished turn becomes a memory bank entry, starting with the last 30 days; todo and plan snapshots too (see MEMORY_BANKING.md)	omp, pi, Claude Code, Codex, Antigravity — not Cursor
   Context hooks	project brief, matching memories and your org's policy instructions injected before the model answers; org tool and command rules checked before every tool call	Claude Code, Codex, omp
   Memory tools (MCP)	superpi mcp registered so the model can call memory tools	omp, Claude Code, Codex

   A feature only appears when the harness is detected (its binary on PATH, or its data directory present). A What syncs block lists every sync category (prompt history from every harness, session transcripts, memories, usage from HarnessLink's old built-in agent, gateway usage, device profile), all ✓. Enter sets it all up, c customizes (toggle any sync category, harness or feature, including restore), q quits.

2. Sign in. A HarnessLink Cloud account is required. The device code is shown

   large, the browser opens on the approval page (o reopens it, c copies the code), and a spinner waits for your approval. Already signed in? It shows the account and moves on. Cancelling (Esc) or failing stops with "Setup is not complete: a HarnessLink Cloud account is required — run superpi cloud setup again" and exit code 1.

3. Everything else runs by itself on a live checklist (spinner → ✓ or ✗

   with a one-line detail): cloud sync on, with your sync category choices → the HarnessLink service (launchd on macOS, a systemd --user unit on Linux, a logon task on Windows) → per harness: gateway routing, transcript sync, autobank, context hooks (see USAGE.md), memory tools → restore (additive: never overwrites a local file): sessions, prompt history, memories, harness setup (agents, commands, skills, rules), old memories (MemPalace, Hermes) → verify (the gateway answers and is signed in, one prompt-history pass over every harness, the memory bank from every harness, a real sync round trip, sync health). A failed step does not stop the ones after it. The HarnessLink service notices harnesses turned on after it started; it does not need a restart.

4. Summary. ✓/✗ per step with the retry command for each failure, what

   is on now, and the standalone command for every piece.

Every piece stays a command of its own for manual setups:

Without a terminal, superpi cloud setup prints this list and exits 1.

The hosted service at harnesslink.sh is the default. To run against your own Cloudflare stack instead, set it up first — see CLOUD_SETUP.md.

The dashboard's Setup page shows an eight-step checklist and ticks each step off from your real cloud data; the public copy lives at harnesslink.sh/docs#connect-the-cloud. The canonical definitions are code, not prose: cloud/web/src/lib/setupSteps.ts — update that file and this table together.

superpi update

A picker over every harness on the machine — omp first, then HarnessLink itself, then Claude Code, Codex and others that are installed — running each one's own updater. HarnessLink updates itself by re-running the installer from harnesslink.sh. Non-interactive runs update HarnessLink directly.

Old-agent leftovers. HarnessLink's old built-in agent left git worktrees in ~/.superpi/wt (they can reach many GB) and the output of its background jobs in ~/.superpi/run/daemons (logs only, often hundreds of MB). superpi update and the superpi home screen offer to remove them, showing their combined size; superpi cleanup does it on demand. Nothing is deleted without your yes, and worktrees with uncommitted changes are listed and never deleted without saying so.

An update tidies after itself. Re-running the installer over ~/.superpi-src:

• removes whatever the previous version shipped that this one does not: whole

  directories (the old built-in agent, the native addon and their build outputs) and single files alike — a plain extract only adds and overwrites;

• rebuilds node_modules from scratch when the set of packages changed, so

  the old tree's dependencies (1.4 GB before HarnessLink became a controller) do not linger, and says how much space it freed;

• removes a .git left by a pre-cutover clone, so superpi update never

  turns into a private-repository credential prompt;

• keeps build products of what it still ships (node_modules, dist,

  generated sources) and dotfiles at the root of the tree. A bazel cache an old native build left elsewhere is named, never deleted.

The installer refuses to install over a git checkout at a custom --dir, or over any non-empty directory that is not already a HarnessLink install — it would otherwise overwrite and prune your files.

superpi: command not found ~/.bun/bin is not on your PATH. Add it and open a new shell:

export PATH="$HOME/.bun/bin:$PATH"

superpi says you are not signed in, or shows an empty setup Check which config directory is in use — a stray SUPERPI_CONFIG_DIR (or, from 17.5.55, HARNESSLINK_CONFIG_DIR) in your environment will point the CLI at an empty profile:

echo "$HARNESSLINK_CONFIG_DIR $SUPERPI_CONFIG_DIR"    # expect both empty

Both names work; when both are set, HARNESSLINK_CONFIG_DIR wins. SUPERPI_CONFIG_DIR accepts either a relative name (resolved under $HOME, default .superpi) or an absolute path (used as-is as the full config root). A relative name such as cfg resolves to $HOME/cfg; an absolute path such as SUPERPI_CONFIG_DIR=/tmp/cfg uses /tmp/cfg directly. To run against a different profile, set SUPERPI_CONFIG_DIR to an absolute path, or set HOME to redirect all relative resolution.

Undo the wiring before deleting anything. The harnesses' own configs point at HarnessLink (gateway base URLs, hooks, MCP entries); deleting the superpi binary first leaves them pointing at nothing, and connected harnesses then fail with "connection refused".

superpi gateway disconnect              # put back each harness's own provider settings
superpi harness context --remove        # remove HarnessLink's context hooks (Claude Code, Codex, omp)
superpi gateway service uninstall       # stop and remove the LaunchAgent / systemd unit / logon task
superpi cloud logout                    # optional: unlink this machine from your account
superpi add --list                      # optional: registry add-ons HarnessLink put in harness skill folders
superpi remove <name>                   #   remove each one (only the files HarnessLink wrote)

Then remove HarnessLink's MCP entry from each harness you registered it in:

Finally remove HarnessLink itself:

rm -f ~/.bun/bin/superpi
rm -rf ~/.superpi-src
rm -rf ~/.superpi          # ⚠️ also deletes local history, memory and sessions

On Windows, delete %USERPROFILE%\.bun\bin\superpi.cmd and %USERPROFILE%\.superpi-src instead.

This leaves omp, pi, Claude Code, Codex and every other harness installed — they are separate programs. In particular, ~/.bun/bin/pi is the pi harness, not part of HarnessLink. Remove a harness with its own uninstaller if you want it gone.