npm one-liner install for iterate-harness — the dedicated agent harness for the iterate review/fix loop (ih CLI, React TUI, six iterate_* tools, engine-enforced convergence).

npm install -g iterate-harness
ih --version        # first run bootstraps the Python side, then prints the version

What this package is (and is not)

The harness itself is a Python package. This npm package is a thin distribution wrapper: it does not re-implement anything, it just makes ih installable with npm and keeps it up to date.

Right after npm install finishes, a postinstall hook creates the managed venv and installs the harness — so ih is ready to use immediately. The delegation logic used at install time and at runtime is the same:

Finds a Python interpreter >= 3.10 (py -3 / python / python3, overridable via ITERATE_HARNESS_PYTHON).
Creates a managed virtualenv at ~/.iterate-harness-npm/venv (overridable via ITERATE_HARNESS_NPM_HOME).
pip installs the harness pinned to this npm package's version — npm 1.6.0 always installs harness v1.6.0. Upgrading the npm package automatically re-installs the matching harness version on the next run. The preferred source is the official PyPI index: pip resolves iterate-harness==X.Y.Z against your configured mirror (e.g. pypi.tuna.tsinghua.edu.cn), so installs work even when GitHub is unreachable or its TLS cert fails to verify. If PyPI is unavailable, the wrapper falls back to the pre-built wheel on the GitHub release (frontend assets baked in, like iterate-skill-installer ships pre-wrapped assets), then the pinned source archive as a final resort. Every artifact the wrapper downloads itself is hashed with SHA256 and verified against the release's .sha256 sidecar before pip installs it — a tampered or corrupted download is refused, never installed.
Delegates to the venv's real ih executable with argv, stdio, signals and exit codes forwarded.

If the install during npm install can't complete (no Python, no network, or ITERATE_HARNESS_SKIP_INSTALL=1), the hook prints a notice without failing the npm install, and ih still installs on its first run — a lazy fallback keeps the package usable either way.

Interactive experience

ih greets you with a cyan ITERATE ASCII banner on every run (claude-code style), and the first install runs an interactive wizard like iterate-skill-installer:

It prints an "Installing" box with the pinned version and runtime location.
It asks Install iterate-harness vX.Y.Z ...? [Y/n] before downloading — decline and it exits cleanly (code 0) instead of failing.
When done, it prints a "Done" box with getting-started tips (ih --help, ih status, ih iterate --help).

All UI output goes to stderr, so ih --version | jq '...' still gives you clean machine-readable stdout.

The React TUI's frontend dependencies (node_modules) are installed automatically by the harness itself on first TUI launch — npm users always have Node, so the TUI always works.

Requirements

Node.js >= 16 (you have it — you installed this via npm)
Python >= 3.10 (ITERATE_HARNESS_PYTHON=/path/to/python3.12 to override)
Network access to registry.npmjs.org (done), pypi.org and github.com (for the one-time pip install)

Environment variables

Variable	Effect
`ITERATE_HARNESS_PYTHON`	Use this interpreter instead of auto-detection
`ITERATE_HARNESS_NPM_HOME`	Runtime dir (default `~/.iterate-harness-npm`)
`ITERATE_HARNESS_INSTALL_URL`	Install from this pip URL instead of the pinned release wheel (e.g. a git branch for testing)
`ITERATE_HARNESS_SKIP_INSTALL=1`	Skip bootstrap entirely; just run the already-installed `ih`

npx (no global install)

npx -y iterate-harness iterate review --changed

Uninstall

npm uninstall -g iterate-harness
rm -rf ~/.iterate-harness-npm   # the managed venv

Versioning

This package's version is kept in lockstep with the harness: wrapper x.y.z installs harness tag vx.y.z. The wrapper is maintained in the iterate-skill monorepo at harness/iterate-harness/npm/, synced to the iterate-harness release repo via git subtree and published to npm from there.

⚠️ Disclaimer

This package is provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. The harness it installs performs automated code review and fixing, and all changes it produces in normal mode are generated by AI models and may introduce bugs, regressions, or unintended behavior. You are solely responsible for the code generated, modified, or committed as a result of its use. See the iterate-harness README for full details and safety guidance.