macOS Install Guide

Execution note: Commands on this page beyond installation and bootstrap are operational detail for your agent or an advanced operator. If you are working through an agent, describe the outcome you want; the agent should explain material changes, request any needed approval, and report evidence when it finishes.

First time using AIWG? Begin with Install, Connect, and Verify. This guide assumes AIWG is already installed, `all` is deployed for your provider, and `aiwg-regenerate` has connected the agent to this project.

Use this guide when installing AIWG on a Mac, especially if `npm install -g aiwg` fails with `EACCES` under `/usr/local/lib/node_modules`.

For the complete agent/steward setup path after the Mac install succeeds, see the Agentic Install Runbook.

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

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 all --provider <provider>
aiwg index build --all
aiwg regenerate --provider <provider>
aiwg status --probe --json
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