Skip to content

macos-install.md

Latest commit

 

History

History
149 lines (112 loc) · 4.29 KB

macos-install.md

File metadata and controls

149 lines (112 loc) · 4.29 KB

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:

Recommended Path: nvm

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