guide users on unsupported node instead of crashing on launch

[kevinjosethomas]

• installing under node 20 let the cli download but crash on first launch with an opaque stack trace, since the bundle links node 22+ apis before any code runs.
• the bin entry is now a tiny dependency-free preflight that checks the node version and prints clear upgrade guidance, loading the real startup only once the check passes.
• also bumps the declared engines floor to node 22 so npm warns at install time.

---

Note

Low Risk
Startup-path refactor with isolated, tested version guard; no auth, data, or runtime behavior changes on supported Node.

Overview
On Node 20 (and other versions below 22.8.0), the CLI could install but crash at launch with an opaque error because the bundle links Node 22+ APIs before any user-facing code ran.

cli.ts is now a thin entry that runs a dependency-free assertNodeVersion check first, prints upgrade/reinstall steps, and exits with code 1 when unsupported. Only after the check passes does it dynamically import cli-main.ts, which holds the previous startup path (runCli: compile cache, daemon early launch, owned-session worker, undici dispatcher, main).

engines.node is raised from >=20.x to >=22.8.0 on the root and coding-agent packages so npm can warn at install time. Bun skips the guard; prereleases of exactly 22.8.0 are rejected. Vitest coverage was added for the version guard.

^{Reviewed by Cursor Bugbot for commit 0508a36. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Guide users on unsupported Node versions instead of crashing on launch

• Adds a dependency-free version guard in node-version-check.ts that runs before the module graph loads, logging actionable upgrade instructions and exiting with code 1 when Node is below 22.8.0.
• Refactors cli.ts to check the Node version first, then dynamically import and invoke runCli() from the new cli-main.ts only on supported versions.
• Raises the minimum Node requirement from >=20.0.0 to >=22.8.0 in engines.node for both the root and coding-agent packages.
• Behavioral Change: Bun runtimes bypass the version check; prerelease builds of the exact minimum version (22.8.0-rc.x) are rejected.

^{Macroscope summarized 0508a36.}

[linear]

ENG-4260 Incorrect node version breaks first launch

Having an outdated Node version (I think 20) leads to a state where we can download prime-agent but it completely breaks on first launch. This is a horrible user experience— we should detect it and guide the user through.

Here is Claude's diagnoses:
Let me look at what got installed in this directory.

Listed 1 directory (ctrl+o to expand)

⏺️ prime-agent is installed. Let me check what it is and its help.

⏺️ Bash(ls -la /Users/eligottlieb/.nvm/versions/node/v20.18.1/bin/prime-agent; echo "---"; readlink -f /Users/eligottlieb/.nvm/versions/node/v20.18.1/bin/prime-agent;

e…)

⎿  lrwxr-xr-x 1 eligottlieb 50 Jun 25 13:41 /Users/eligottlieb/.nvm/versions/node/v20.18.1/bin/prime-agent -> ../lib/node_modules/prime-agent/dist/bundle/cli.

js

---

… +12 lines (ctrl+o to expand)

⏺️ The install worked but there's a Node version problem. enableCompileCache requires Node 22+, and your active Node is v20.18.1. Let me confirm requirements and

what's available.

⏺️ Bash(echo "---PKG engines/bin---"; cat /Users/eligottlieb/.nvm/versions/node/v20.18.1/lib/node_modules/prime-agent/package.json 2>/dev/null | python3 -c "import

sys,…)

⎿  ---PKG engines/bin---

name prime-agent

version 0.2.2

… +12 lines (ctrl+o to expand)

⏺️ The issue is clear: prime-agent v0.2.2 was installed under your Node v20.18.1 (currently active via nvm), but its bundle uses enableCompileCache, which only exists

in Node 22+. Let me confirm it runs on Node 22:

⏺️ Bash(~/.nvm/versions/node/v22.21.1/bin/node /Users/eligottlieb/.nvm/versions/node/v20.18.1/lib/node_modules/prime-agent/dist/bundle/cli.js --help 2>&1 | head -40)

⎿  prime-agent - AI coding assistant with an ipython tool

Usage:

… +37 lines (ctrl+o to expand)

⏺️ It works fine under Node 22 — the only problem is your active Node is v20.18.1, and prime-agent's bundle needs Node 22+ (it uses enableCompileCache). The

prime-agent command on your PATH points into the v20 install, so running it bare fails.

Quick way to run it right now

~/.nvm/versions/node/v22.21.1/bin/node \

~/.nvm/versions/node/v20.18.1/lib/node_modules/prime-agent/dist/bundle/cli.js

That launches the interactive chat TUI. You can append a message or files, e.g.:

~/.nvm/versions/node/v22.21.1/bin/node \

~/.nvm/versions/node/v20.18.1/lib/node_modules/prime-agent/dist/bundle/cli.js \

"explain this repo" README.md

Proper fix (recommended) — reinstall under Node 22

So that the plain prime-agent command just works:

nvm use 22.21.1

npm i -g prime-agent

prime-agent --help

Then prime-agent will resolve to the Node 22 install and you can run it directly.

A couple of usage notes from its --help:

• Default provider is google. To use a different model: prime-agent --provider anthropic --model claude-opus-4-8. It reads API keys from env vars (or pass

--api-key).

• prime-agent -p "..." for non-interactive one-shot output; -c to continue the last session.

Want me to go ahead and reinstall it under Node 22 for you so the bare prime-agent command works?

Review in Linear