Skip to content

install-mac.md

Latest commit

 

History

History
217 lines (153 loc) · 5.02 KB

install-mac.md

File metadata and controls

217 lines (153 loc) · 5.02 KB

QuadWork — Mac Installation Guide

Step-by-step guide for installing QuadWork on macOS. Designed for both humans and AI coding agents.

Prerequisites

Check existing tools

node --version   # Need 20+ (24 recommended)
git --version
gh --version

Install missing prerequisites

Node.js 20+ (via nvm — strongly recommended):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.zshrc
nvm install 24
nvm use 24

Why nvm? The QuadWork install step below uses npm install -g. With a Homebrew or .pkg Node, global installs target /usr/local/lib/node_modules/ and fail with EACCES: permission denied unless you use sudo. nvm puts the global prefix inside ~/.nvm/, so npm install -g works without elevated permissions.

Git (included with Xcode Command Line Tools):

xcode-select --install

GitHub CLI:

brew install gh

Authenticate GitHub CLI

gh auth login

This is interactive — the operator must complete the browser-based auth flow. Ask the user to run this command if not already authenticated.

Verify:

gh auth status
# You should see: "Logged in to github.com account <username>"

Install AI Coding Agents

Install one or more of the supported agent CLIs:

# Claude Code (Anthropic)
npm install -g @anthropic-ai/claude-code

# Codex CLI (OpenAI)
npm install -g @openai/codex

# Gemini CLI (Google) — if using Gemini agents
npm install -g @google/gemini-cli

Authenticate agent CLIs

Each CLI requires a one-time interactive login:

# Claude Code — follow the login prompt
claude

# Codex — follow the login prompt
codex

These are interactive steps. Ask the operator to run each command and complete the login flow.

Install QuadWork

npm install -g quadwork@latest

Verify:

quadwork --version
# You should see the version number (e.g., 1.14.5)

Troubleshooting: EACCES: permission denied

If you see an error like:

npm error code EACCES
npm error syscall mkdir
npm error path /usr/local/lib/node_modules/quadwork

your Node is installed system-wide (Homebrew or the .pkg installer) and the global prefix is not writable by your user. Pick one:

  • Switch to nvm (recommended) — see the Prerequisites section above, then re-run npm install -g quadwork@latest.
  • Run once with npx (no global install): 
    npx quadwork@latest init
npx quadwork@latest start
  • Install with sudo (not recommended — leaves root-owned files in your global node_modules): 
    sudo npm install -g quadwork@latest

Initialize & Start

Interactive setup

quadwork init

This is interactive. The operator will be prompted to configure their first project (name, repo, working directory, agent backends).

Start the server

quadwork start

You should see output like:

QuadWork dashboard: http://localhost:8400

Open the dashboard URL in your browser to access the web UI.

Create Your First Project

  1. Open the dashboard at http://localhost:8400
  2. Click "+ New Project" or navigate to /setup
  3. Fill in the project details:
    • Name: Your project name
    • Repo: GitHub repo in owner/repo format
    • Working directory: Absolute path to the repo clone
    • Agent backends: Choose Claude, Codex, or Gemini for each agent role
  4. Click Create

QuadWork will:

  • Create worktree directories for each agent (e.g., project-head/, project-dev/, project-re1/, project-re2/)
  • Seed AGENTS.md files for each role

Trust Prompt (Claude Code)

On first launch, Claude Code agents may get stuck at a "Do you trust this directory?" prompt. QuadWork v1.14.5+ automatically pre-trusts worktree directories for Claude-configured agents during project creation.

If agents are still stuck (e.g., upgraded from an older version), manually pre-trust each worktree:

# Run in each worktree directory
cd /path/to/project-head && claude -p "echo ok"
cd /path/to/project-dev && claude -p "echo ok"
cd /path/to/project-re1 && claude -p "echo ok"
cd /path/to/project-re2 && claude -p "echo ok"

Discord / Telegram Bridge (Optional)

Discord bridge

  1. Open the project page in the dashboard
  2. Click the Discord widget
  3. Enter your Discord bot token and channel ID
  4. Click Start

Telegram bridge

  1. Open the project page in the dashboard
  2. Click the Telegram widget
  3. Enter your Telegram bot token and chat ID
  4. Click Start

Note: Bridges are configured per-project in ~/.quadwork/config.json. See the dashboard Telegram/Discord widgets for setup.

Stopping & Restarting

# Stop the server (Ctrl+C if running in foreground)
# Or if running in background:
quadwork stop

# Restart
quadwork start

For persistent background operation on Mac, consider using pm2:

npm install -g pm2
pm2 start "quadwork start" --name quadwork
pm2 save