macOS Install Guide

macOS Install Guide

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

First time using AIWG? Begin with Install, Connect, and Verify. This guide assumes

AIWG is connected to the target project and your provider session can read the deployed context.

Use this guide when installing AIWG on a Mac, especially if the agent-assisted AIWG installation procedure 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

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

Use AIWG to complete this documented outcome: This avoids root-owned global npm directories and works on both Intel and Apple Silicon Macs.
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

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:

Use AIWG to complete this documented outcome: Use npm's current user-prefix recovery
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Do not use `sudo the agent-assisted AIWG installation procedure` 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.

Use AIWG to complete this documented outcome: 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.
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

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, the agent-owned use operation, 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 the install option        # one-time; provides the C/C++ toolchain
npm rebuild better-sqlite3     # or re-run the opt-in install that failed

For PDF rasterization specifically (the agent-owned corpus operation), install poppler via Homebrew:

brew install poppler

After AIWG Installs

Deploy AIWG from the project root:

Use AIWG to complete this documented outcome: Deploy AIWG from the project root
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

the agent-owned use operation performs the index, context, and readiness checks itself. Use the agent-owned status operation for an explicit audit or the agent-owned doctor operation when the result identifies a recovery step.

If the agent-assisted AIWG installation procedure 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