Macos Install

macOS Install Guide

Use this guide when installing AIWG on a Mac, especially if `npm install -g aiwg`

fails with `EACCES` under `/usr/local/lib/node_modules`.

Verified against the npm and Node.js documentation on 2026-06-02:

  • npm recommends installing Node.js and npm with a Node version manager such as

`nvm` because installer-managed global directories can cause permission errors:

<https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/>

  • npm's current `EACCES` recovery guide recommends either using a Node version

manager or changing npm's global prefix to a user-owned directory:

<https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally/>

  • The Node.js download page lists Node 24 as the current LTS line on

2026-06-02. AIWG supports Node 20 or newer; new installs should use Node 24:

<https://nodejs.org/en/download>

This avoids root-owned global npm directories and works on both Intel and Apple

Silicon Macs.

# Install nvm. Check https://github.com/nvm-sh/nvm for the newest command.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

# Load nvm in the current zsh session.
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

# Install current LTS Node.js and AIWG.
nvm install 24
nvm use 24
npm install -g aiwg

# Verify.
node --version
npm --version
aiwg --version

If `nvm: command not found` appears after the install script, open a new terminal

or run:

source ~/.zshrc

If `~/.zshrc` does not exist, create it and rerun the nvm installer:

touch ~/.zshrc

If Node Is Already Installed and npm Fails With EACCES

This error means npm is trying to write global packages into a directory your

user does not own, commonly `/usr/local/lib/node_modules`.

npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path /usr/local/lib/node_modules/aiwg

Use npm's current user-prefix recovery:

npm config set prefix ~/.local
echo 'PATH="$HOME/.local/bin:$PATH"' >> ~/.profile
echo 'source ~/.profile' >> ~/.zprofile
source ~/.profile

npm install -g aiwg
aiwg --version

Do not use `sudo npm install -g aiwg` as the default fix. It may install AIWG

once, but it can leave root-owned npm files that cause later upgrades and global

package installs to fail.

Homebrew Path

Homebrew is acceptable if the Homebrew prefix is user-writable and first in

`PATH`. It is most useful for users who already manage developer tools with

Homebrew.

brew install node@24
brew link --overwrite node@24
npm install -g aiwg
aiwg --version

If Homebrew Node still sends npm global installs to `/usr/local/lib/node_modules`

and fails with `EACCES`, use the `~/.local` npm prefix recovery above or switch

to `nvm`.

Optional native features (Xcode Command Line Tools)

AIWG's base install never needs build tools — its native dependencies

(`better-sqlite3`, `node-pty`, `hnswlib-node`) are `optionalDependencies` that

ship prebuilt macOS binaries and are skipped silently if they can't install. The

CLI, `aiwg use`, and all the text-based tooling work without them.

A few opt-in features use native modules: the SQLite graph backend

(`better-sqlite3`), semantic search / embeddings (`@xenova/transformers` +

`onnxruntime-node`, installed on demand), and PDF page rasterization for

vision extraction (poppler `pdftoppm`). These normally use prebuilt binaries on

Mac. If one ever fails to build (an unusual Node version, or a module without a

matching prebuilt), install Apple's Command Line Tools and retry:

xcode-select --install        # one-time; provides the C/C++ toolchain
npm rebuild better-sqlite3     # or re-run the opt-in install that failed

For PDF rasterization specifically (`aiwg corpus vision-extract --rasterize`),

install poppler via Homebrew:

brew install poppler

After AIWG Installs

Deploy AIWG from the project root:

cd /path/to/your/project
aiwg use sdlc
aiwg doctor

If `npm install -g aiwg` succeeds but `aiwg` is not found, check npm's global

binary directory:

npm config get prefix
echo "$PATH"

The `bin` directory under the npm prefix must be in `PATH`. For the `~/.local`

prefix, that means:

echo 'PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile