README Quick Start fails on macOS: Node 26 incompatibility and missing tree-sitter CLI prerequisite

[bobbywhitesfdc]

Summary

Following the README's Quick Start on macOS (Apple Silicon, fresh Homebrew toolchain), both pnpm install and pnpm build fail out of the box. Two prerequisites are not documented.

Environment

• macOS (Apple Silicon), Darwin 25.4.0
• Homebrew-installed Node and pnpm
• Repo at main (commit 4670b96)

Issue 1 — Node version ceiling not stated

The README says "Node.js >= 20", but tree-sitter@0.25.0's native binding fails to compile against Node 26's V8 headers. Homebrew's default node formula is currently 26.0.0, so anyone running brew install node lands on a broken version.

Representative error from pnpm install:

.../node_modules/tree-sitter install: /Users/.../node-gyp/26.0.0/include/node/v8-internal.h:1604:19:
  error: non-static data member 'is_convertible_v' cannot be declared as a template
.../node_modules/tree-sitter install:  error: 'is_convertible_v' cannot be specialized:
  Users are not allowed to specialize this standard library entity
.../node_modules/tree-sitter install: 3 warnings and 20 errors generated.
.../node_modules/tree-sitter install: make: *** [Release/obj.target/tree_sitter_runtime_binding/src/binding.o] Error 1
.../node_modules/tree-sitter install: gyp ERR! node -v v26.0.0
ELIFECYCLE  Command failed with exit code 1.

The repo's package.json pins volta.node to 22.22.1, which works — so Volta users are fine, but the README's plain "Node.js >= 20" guidance points the rest of us at a broken version.

Suggestion: state an upper bound (e.g. "Node 20–22 LTS") or recommend Volta explicitly so the pinned version is honored.

Issue 2 — tree-sitter CLI is a hidden prerequisite

packages/parser-tree-sitter invokes tree-sitter generate in its prebuild and build scripts, but the CLI is not a devDependency — it has to be installed system-wide. Neither the README nor CONTRIBUTING.md mentions this. (The preinstall.cjs hints at cargo install tree-sitter-cli inside a warning branch that only fires when parser.c is missing, which it usually isn't.)

pnpm install succeeds, but pnpm build fails:

@agentscript/parser-tree-sitter:build: > tree-sitter generate
@agentscript/parser-tree-sitter:build: sh: tree-sitter: command not found
ELIFECYCLE  Command failed with exit code 1.

On macOS, the fix is brew install tree-sitter-cli. Worth noting that brew install tree-sitter installs only the library — the formulas were recently split, so following an obvious-looking guess gets you the wrong package.

Suggestion: add a Prerequisites bullet for the tree-sitter CLI with install commands per OS (brew, cargo, etc.).

Working setup on macOS

brew install node@22
brew link --overwrite --force node@22
brew install tree-sitter-cli
pnpm install
pnpm build

After this, pnpm build completes cleanly (16/16 packages) and pnpm ui:dev runs.

[dsorajisto]

Hi — I'd like to take Issue 2 specifically (the undocumented tree-sitter CLI prerequisite). Issue 1 (Node version compatibility) is covered by #23 and #27.

Approach: docs-only update to the README Prerequisites section, recommending mise install as the primary path (which respects the pinned 0.25.x line in mise.toml) with a manual-install fallback that explicitly lists the tree-sitter CLI. I also call out the macOS Homebrew gotcha — brew install tree-sitter installs only the C library; the CLI is a separate tree-sitter-cli formula (and currently ships 0.26.x, a minor mismatch with the pin).

I considered an auto-install fix (adding tree-sitter-cli as a devDependency of packages/parser-tree-sitter) but ruled it out — pnpm 10's default policy blocks install scripts, and the repo already lives with that policy (see the "Ignored build scripts" warnings for esbuild, core-js, keytar, etc.). Allowlisting tree-sitter-cli via pnpm.onlyBuiltDependencies would be a security-policy change worth its own discussion. Docs-first feels like the right tradeoff for this issue; we can revisit auto-install later if maintainers want.

PR incoming shortly.

[awli]

Thanks for reporting this issue!

I think internally we knew about this issue but didn't really think about it. I think that addressing this would be primarily a docs change, would you agree?