Repository navigation
README Quick Start fails on macOS: Node 26 incompatibility and missing tree-sitter CLI prerequisite #33
Description
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(commit4670b96)
Issue 1 — Node version ceiling not stated
The README says "Node.js >= 20", but [email protected]'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 buildAfter this, pnpm build completes cleanly (16/16 packages) and pnpm ui:dev runs.
Activity
dsorajisto commentedon May 13, 2026
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 commentedon May 13, 2026
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?
docs(readme): document tree-sitter CLI prereq and recommend mise (#36)
setu4993 commentedon Nov 14, 2026
Covered by #36. The README's Prerequisites section now recommends
mise install, which installs the pinned Node 22 and tree-sitter CLI 0.25.x frommise.toml, and the manual setup lists both, including the tree-sitter CLI requirement. Thanks for flagging it!