Prerequisites¶

This document provides detailed installation instructions for all required tools across different platforms.

Required Tools¶

The amplihack framework requires the following tools. Each entry explains what the tool does and why amplihack needs it:

Quick Check¶

Before installing amplihack, verify your prerequisites with this script:

# Copy-paste this into your terminal — no installation required
node --version && npm --version && uv --version && git --version && echo "All prerequisites OK"

After installing amplihack, running amplihack will also check for missing tools and display installation instructions.

Platform-Specific Installation¶

macOS¶

Package Manager: We recommend using Homebrew

Install Homebrew (if not already installed)¶

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Required Tools¶

# Node.js and npm (installed together)
brew install node

# uv
brew install uv

# git
brew install git

Verify Installation¶

node --version   # Should show v18.x or higher
npm --version    # Should show 9.x or higher
uv --version     # Should show version info
git --version    # Should show 2.x or higher

Linux¶

Package Managers: apt (Ubuntu/Debian), dnf (Fedora/RHEL), pacman (Arch)

Ubuntu/Debian¶

# Node.js and npm
sudo apt update
sudo apt install nodejs npm

# uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# git
sudo apt install git

Fedora/RHEL/CentOS¶

# Node.js and npm
sudo dnf install nodejs npm

# uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# git
sudo dnf install git

Arch Linux¶

# Node.js and npm
sudo pacman -S nodejs npm

# uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# git
sudo pacman -S git

Verify Installation¶

node --version   # Should show v18.x or higher
npm --version    # Should show 9.x or higher
uv --version     # Should show version info
git --version    # Should show 2.x or higher

Windows Subsystem for Linux (WSL)¶

Recommended: Use the Linux installation instructions for your WSL distribution (usually Ubuntu)

WSL is detected automatically and will show appropriate Linux-based installation commands.

Ubuntu WSL¶

# Node.js and npm
sudo apt update
sudo apt install nodejs npm

# uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# git
sudo apt install git

After Installation¶

Restart your WSL terminal to ensure all tools are in your PATH:

# Close and reopen your WSL terminal, then verify:
node --version
npm --version
uv --version
git --version

Windows (Native)¶

Package Managers: winget (recommended) or Chocolatey

Using winget (Windows 10 1709+)¶

# Node.js and npm (installed together)
winget install OpenJS.NodeJS

# uv
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# git
winget install Git.Git

Using Chocolatey¶

# Install Chocolatey first (if not installed):
# See https://chocolatey.org/install

# Node.js and npm
choco install nodejs

# uv
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# git
choco install git

Verify Installation¶

node --version   # Should show v18.x or higher
npm --version    # Should show 9.x or higher
uv --version     # Should show version info
git --version    # Should show 2.x or higher

Configure PowerShell UTF-8 Encoding (Required for Windows)¶

AmplihHack uses Unicode characters (emojis, checkmarks) in output. Windows PowerShell defaults to Code Page 437, which causes these characters to display incorrectly as garbled text (e.g., ✅ instead of ✅).

Fix this by adding UTF-8 configuration to your PowerShell profile:

# Create PowerShell profile if it doesn't exist
if (!(Test-Path $PROFILE)) {
    New-Item -ItemType File -Path $PROFILE -Force
}

# Add UTF-8 configuration
Add-Content $PROFILE @"
# Set console to UTF-8 to properly display Unicode characters (emojis, special characters)
[console]::OutputEncoding = [System.Text.Encoding]::UTF8
`$OutputEncoding = [System.Text.Encoding]::UTF8
"@

# Reload profile
. $PROFILE

To temporarily enable UTF-8 in the current session:

chcp 65001

Verify encoding:

[console]::OutputEncoding
# Should show: BodyName: utf-8, CodePage: 65001

Tool-Specific Documentation¶

Node.js¶

Purpose: Runtime for claude-trace (enhanced debugging and tracing)

Official Documentation: https://nodejs.org/

Minimum Version: v18.0.0

Alternative Installation Methods:

• nvm (Node Version Manager): Recommended for managing multiple Node.js versions
• macOS/Linux: https://github.com/nvm-sh/nvm
• Windows: https://github.com/coreybutler/nvm-windows

npm¶

Purpose: Package manager for installing claude-trace

Official Documentation: https://www.npmjs.com/

Note: npm is automatically installed with Node.js

Verify npm Configuration:

npm config get prefix  # Should show global installation directory

uv¶

Purpose: Fast Python package installer and resolver

Official Documentation: https://docs.astral.sh/uv/

Alternative Installation Methods:

• pip: pip install uv (not recommended, slower)
• cargo: cargo install uv (if you have Rust toolchain)

Configuration:

# Optional: Configure uv cache location
export UV_CACHE_DIR=/path/to/cache

# Optional: Use specific Python version
uv python install 3.12

git¶

Purpose: Version control and repository management

Official Documentation: https://git-scm.com/

Minimum Version: 2.0.0

Configuration:

# Set up your identity
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Verify configuration
git config --list

Required Tools (After Prerequisites)¶

Claude CLI¶

Purpose: Official Claude Code command-line interface

Documentation: https://code.claude.com/docs/en/setup

Installation — pick the method for your platform:

Note: The older npm install -g @anthropic-ai/claude-code method is deprecated and no longer recommended. Use the platform-specific installers above.

Verification:

claude --version
# Should show version information

Auto-Installation (Opt-In):

export AMPLIHACK_AUTO_INSTALL=1

When set, the framework will automatically install Claude CLI if missing. This requires explicit opt-in for security.

claude-trace¶

Purpose: Enhanced debugging and traffic logging for Claude Code

Installation (Required):

npm install -g @mariozechner/claude-trace

Note: This is a required dependency as of the simplified implementation. Install it during initial setup.

Documentation: Part of claude-code ecosystem (https://github.com/mariozechner/claude-trace)

Usage:

• Enabled by default (AMPLIHACK_USE_TRACE=1)
• To temporarily disable and use plain claude: export AMPLIHACK_USE_TRACE=0

Verification:

claude-trace --version
# Should show version information

Troubleshooting¶

"command not found" errors¶

Problem: Tool installed but not in PATH

Solution:

macOS/Linux:

# Check if tool is installed
which node npm uv git

# If missing from PATH, add to your shell profile:
# For bash:
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh:
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Windows:

# Add to PATH via System Settings:
# 1. Search for "Environment Variables"
# 2. Edit "Path" variable
# 3. Add tool installation directories
# 4. Restart PowerShell

Permission errors during npm install¶

Problem: "permission denied" when installing npm packages globally

Solution:

Option 1: Use a Node version manager (recommended)

# Install nvm and use it to install Node.js
# This avoids permission issues

Option 2: Fix npm permissions

# Create a directory for global packages
mkdir ~/.npm-global

# Configure npm to use the new directory
npm config set prefix '~/.npm-global'

# Add to PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile

Option 3: Use sudo (not recommended)

sudo npm install -g <package>
# Not recommended due to security implications

uv installation fails¶

Problem: uv installer script fails or not found

Solution:

# Try alternative installation method
pip install uv

# Or if you have Rust:
cargo install uv

# Verify installation
uv --version

Node.js version too old¶

Problem: Node.js version < 18

Solution:

Using nvm:

# Install latest LTS version
nvm install --lts
nvm use --lts

Using package manager:

# macOS
brew upgrade node

# Ubuntu/Debian - use NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# Fedora
sudo dnf install nodejs

# Windows
winget upgrade OpenJS.NodeJS

Verification Script¶

Run this script to verify all prerequisites:

#!/bin/bash

echo "Checking prerequisites..."
echo

# Check Node.js
if command -v node &> /dev/null; then
    echo "✓ Node.js: $(node --version)"
else
    echo "✗ Node.js: Not found"
fi

# Check npm
if command -v npm &> /dev/null; then
    echo "✓ npm: $(npm --version)"
else
    echo "✗ npm: Not found"
fi

# Check uv
if command -v uv &> /dev/null; then
    echo "✓ uv: $(uv --version)"
else
    echo "✗ uv: Not found"
fi

# Check git
if command -v git &> /dev/null; then
    echo "✓ git: $(git --version)"
else
    echo "✗ git: Not found"
fi

# Check claude
if command -v claude &> /dev/null; then
    echo "✓ claude: $(claude --version)"
else
    echo "✗ claude: Not found"
fi

echo
echo "For installation instructions, see docs/PREREQUISITES.md"

Next Steps¶

After installing all prerequisites:

1. Verify installation: Run amplihack to check all tools are detected
2. Install claude-trace (optional): Automatically installed on first use
3. Configure git: Set up your name and email
4. Start using AmplihHack: See README.md for usage instructions

Support¶

If you encounter issues not covered in this guide:

1. Check the troubleshooting section above
2. Review the official documentation for each tool
3. Search for existing issues on GitHub
4. Create a new issue with:
5. Your platform and OS version
6. Command output showing the error
7. Steps you've already tried

Last Updated: 2025-10-01