Multiple installation options are available for macOS users, from package managers to direct installation.

Package Managers

Homebrew (Recommended)

Coming Soon

Homebrew formula is in development. For now, use npm installation.

# Coming soon
brew install commitweave

MacPorts

Coming Soon

MacPorts package is in development.

# Coming soon
sudo port install commitweave

Node.js Package Managers

The most reliable method is using Node.js package managers:

npm install -g @typeweaver/commitweave

yarn global add @typeweaver/commitweave

pnpm add -g @typeweaver/commitweave

Prerequisites

Ensure you have the required dependencies:

Install Node.js

Download from nodejs.org or use a version manager:

# Using Homebrew
brew install node

# Using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

Install Git

Git comes pre-installed on macOS, but you can update it:

# Check current version
git --version

# Update via Homebrew
brew install git

Install CommitWeave

Choose your preferred package manager and install globally:

npm install -g @typeweaver/commitweave

macOS-Specific Features

Terminal Integration

Add shell completion for enhanced experience:

# Add to ~/.bash_profile or ~/.bashrc
eval "$(commitweave completion bash)"

# Add to ~/.zshrc
eval "$(commitweave completion zsh)"

# Add to ~/.config/fish/config.fish
commitweave completion fish | source

Xcode Integration

For Xcode users, you can integrate CommitWeave with Xcode's source control:

Build Phase Script: Add a custom build phase that runs CommitWeave validation
Pre-commit Hook: Set up Git hooks in your Xcode project

# In your Xcode project root
echo "#!/bin/sh\ncommitweave check" > .git/hooks/commit-msg
chmod +x .git/hooks/commit-msg

Apple Silicon (M1/M2) Notes

CommitWeave works natively on Apple Silicon Macs without any special configuration.

If you encounter issues with Node.js on Apple Silicon:

# Check architecture
uname -m

# If needed, install Rosetta 2
sudo softwareupdate --install-rosetta

Troubleshooting

Permission Issues

macOS may require additional permissions for global npm installs:

# Fix npm permissions
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# Or use npm prefix
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile

Gatekeeper Warnings

macOS Gatekeeper might warn about unsigned binaries:

Go to System Preferences > Security & Privacy
Click "Allow Anyway" if prompted
Or disable Gatekeeper temporarily:

sudo spctl --master-disable
# Remember to re-enable: sudo spctl --master-enable

Command Not Found

If commitweave command is not found after installation:

# Check if it's installed
which commitweave
npm list -g @typeweaver/commitweave

# Add npm global bin to PATH
echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.zshrc
source ~/.zshrc

Next Steps

After installation, set up CommitWeave for your workflow:

Initialize configuration: commitweave init
Set up AI providers: Configure OpenAI or Anthropic API keys
Install VSCode extension: Available in the marketplace

See the getting started guide for detailed setup instructions.

macOS Installation