Installation Guide

November 12, 2025 · View on GitHub

Complete installation instructions for ClaudeForge on all supported platforms.

Prerequisites

Required

  • Claude Code 2.0 or later
  • Operating System: macOS, Linux, or Windows
  • Git (for change detection by guardian agent)
  • Terminal access (macOS/Linux) or PowerShell (Windows)

Installation Methods

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.sh | bash

Windows (PowerShell as Administrator)

iwr https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.ps1 -useb | iex

What this does:

  1. Downloads the installer script
  2. Prompts for installation scope (user-level or project-level)
  3. Copies all components to appropriate directories
  4. Creates backups of any existing installations
  5. Optionally installs quality hooks

Method 2: Manual Git Clone

# Clone the repository
git clone https://github.com/alirezarezvani/ClaudeForge.git

# Navigate to directory
cd ClaudeForge

# Run installer
./install.sh  # macOS/Linux
# or
.\install.ps1  # Windows

Method 3: Manual Installation (Advanced)

If you prefer to manually copy files:

Step 1: Download Components

Download the latest release from: https://github.com/alirezarezvani/ClaudeForge/releases

Step 2: Choose Installation Scope

User-Level (Recommended) - Available in all Claude Code projects:

# macOS/Linux
INSTALL_DIR="$HOME/.claude"

# Windows
$INSTALL_DIR="$env:USERPROFILE\.claude"

Project-Level - Available only in current project:

# macOS/Linux
INSTALL_DIR="./.claude"

# Windows
$INSTALL_DIR=".\.claude"

Step 3: Copy Components

# Create directories
mkdir -p "$INSTALL_DIR/skills"
mkdir -p "$INSTALL_DIR/commands"
mkdir -p "$INSTALL_DIR/agents"

# Copy skill
cp -r skill "$INSTALL_DIR/skills/claudeforge-skill"

# Copy slash command
cp -r command "$INSTALL_DIR/commands/enhance-claude-md"

# Copy guardian agent
cp agent/claude-md-guardian.md "$INSTALL_DIR/agents/"

Step 4: Restart Claude Code

Close and restart Claude Code to load the new components.

Installation Scopes

User-Level Installation

Location: ~/.claude/ (or %USERPROFILE%\.claude on Windows)

Advantages:

  • ✅ Available in all Claude Code projects
  • ✅ Install once, use everywhere
  • ✅ Automatic updates apply globally

Use When:

  • You work on multiple projects
  • You want consistent CLAUDE.md standards across all projects
  • You're the primary developer on your machine

Project-Level Installation

Location: ./.claude/ (in your project root)

Advantages:

  • ✅ Project-specific configuration
  • ✅ Version controlled with project (can commit to git)
  • ✅ Team members get same tools

Use When:

  • Different projects need different versions
  • You want to version control the tools
  • Team collaboration requires shared tooling

Verification

After installation, verify all components are installed correctly:

Check Skill Installation

# macOS/Linux
ls -la ~/.claude/skills/claudeforge-skill/

# Windows
dir $env:USERPROFILE\.claude\skills\claudeforge-skill\

Expected output:

analyzer.py
generator.py
template_selector.py
validator.py
workflow.py
SKILL.md
README.md
examples/

Check Command Installation

# macOS/Linux
ls -la ~/.claude/commands/enhance-claude-md/

# Windows
dir $env:USERPROFILE\.claude\commands\enhance-claude-md\

Expected output:

enhance-claude-md.md
README.md

Check Agent Installation

# macOS/Linux
ls -la ~/.claude/agents/claude-md-guardian.md

# Windows
dir $env:USERPROFILE\.claude\agents\claude-md-guardian.md

Test in Claude Code

  1. Restart Claude Code
  2. Open any project
  3. Run the command: 
    /enhance-claude-md
  4. You should see the multi-phase workflow start

Quality Hooks (Optional)

During installation, you'll be asked if you want to install quality hooks.

What are Quality Hooks?

  • Pre-commit validation that checks CLAUDE.md quality before commits
  • Ensures best practices compliance
  • Only available for project-level installations

To Install Hooks:

# During installer
# When prompted: "Would you like to install quality hooks?"
# Type: y

# Or manually:
mkdir -p .claude/hooks
cp hooks/pre-commit.sh .claude/hooks/
chmod +x .claude/hooks/pre-commit.sh

To Use Hooks:

Configure git to use the hook:

# Add to .git/config or use git config
git config core.hooksPath .claude/hooks

Troubleshooting Installation

Issue: "Installation files not found"

Cause: Running installer from wrong directory

Solution:

cd ClaudeForge  # Navigate to repository root
./install.sh     # Run from correct directory

Issue: "Permission denied"

Cause: Installer doesn't have execute permission

Solution:

chmod +x install.sh  # macOS/Linux
# or run with bash explicitly
bash install.sh

Issue: "~/.claude directory not found"

Cause: Claude Code not installed or hasn't been run yet

Solution:

  1. Ensure Claude Code is installed
  2. Run Claude Code at least once to create directory structure
  3. Or let installer create directories (it will prompt)

Issue: Command not recognized after installation

Cause: Claude Code hasn't reloaded components

Solution:

  1. Fully quit Claude Code (not just close window)
  2. Restart Claude Code
  3. Wait a few seconds for components to load
  4. Try command again: /enhance-claude-md

Issue: "Skill not found" error

Cause: Skill directory name mismatch

Solution:

# Verify skill directory name is exactly:
ls ~/.claude/skills/
# Should show: claudeforge-skill

# If different, rename:
mv ~/.claude/skills/old-name ~/.claude/skills/claudeforge-skill

Issue: Windows installer fails with execution policy error

Cause: PowerShell execution policy restricts scripts

Solution:

# Run PowerShell as Administrator
# Set execution policy temporarily:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

# Then run installer:
.\install.ps1

Updating ClaudeForge

To update to a newer version:

Method 1: Using Installer

# Pull latest changes
cd ClaudeForge
git pull origin main

# Run installer (existing installation will be backed up)
./install.sh

Method 2: Manual Update

# Backup current installation
mv ~/.claude/skills/claudeforge-skill ~/.claude/skills/claudeforge-skill.backup

# Copy new version
cp -r skill ~/.claude/skills/claudeforge-skill

# Repeat for command and agent

Uninstallation

To completely remove ClaudeForge:

User-Level Uninstall

# macOS/Linux
rm -rf ~/.claude/skills/claudeforge-skill
rm -rf ~/.claude/commands/enhance-claude-md
rm -f ~/.claude/agents/claude-md-guardian.md

# Windows (PowerShell)
Remove-Item -Recurse -Force $env:USERPROFILE\.claude\skills\claudeforge-skill
Remove-Item -Recurse -Force $env:USERPROFILE\.claude\commands\enhance-claude-md
Remove-Item -Force $env:USERPROFILE\.claude\agents\claude-md-guardian.md

Project-Level Uninstall

# macOS/Linux
rm -rf ./.claude/skills/claudeforge-skill
rm -rf ./.claude/commands/enhance-claude-md
rm -f ./.claude/agents/claude-md-guardian.md
rm -rf ./.claude/hooks  # If quality hooks were installed

# Windows (PowerShell)
Remove-Item -Recurse -Force .\.claude\skills\claudeforge-skill
Remove-Item -Recurse -Force .\.claude\commands\enhance-claude-md
Remove-Item -Force .\.claude\agents\claude-md-guardian.md
Remove-Item -Recurse -Force .\.claude\hooks

After uninstalling, restart Claude Code.

Next Steps

After successful installation:

  1. Read Quick Start Guide: QUICK_START.md
  2. Test the command: Run /enhance-claude-md in a project
  3. Review Architecture: ARCHITECTURE.md
  4. Explore Examples: Check examples/ directory

Support

If you encounter installation issues not covered here:

Installation successful? Proceed to Quick Start Guide →