Setup Guide

Claude Code runs in WSL (Windows Subsystem for Linux), not native Windows. Follow these steps in order to set up WSL2 and install the framework.

Step 1: Enable PowerShell Script Execution

Open PowerShell as Administrator:

# Allow scripts to run (required for automated setup)
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Step 2: Enable WSL2 Features

# Enable WSL2 features
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/notchrisgroves/ia-framework/main/setup/windows/01-install-wsl.ps1" -OutFile "$env:TEMP\01-install-wsl.ps1"; & "$env:TEMP\01-install-wsl.ps1"

The script enables WSL2 features. Restart your computer when prompted.

Step 3: Install Ubuntu and Optimize WSL

After restart, open PowerShell as Administrator and run:

# Install Ubuntu 24.04 and configure WSL settings
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/notchrisgroves/ia-framework/main/setup/windows/02-install-ubuntu-and-harden.ps1" -OutFile "$env:TEMP\02-install-ubuntu-and-harden.ps1"; & "$env:TEMP\02-install-ubuntu-and-harden.ps1"

The script downloads Ubuntu 24.04 (~500MB) with a progress bar and configures optimal WSL settings (memory, CPU, performance).

Step 4: Install Prerequisites in WSL

Install git, bun, GitHub CLI, Claude Code, and other tools inside WSL:

# Run this in WSL Terminal (Ubuntu), NOT PowerShell
curl -fsSL https://raw.githubusercontent.com/notchrisgroves/ia-framework/main/setup/linux/01-install-prerequisites.sh -o /tmp/01-install-prerequisites.sh && chmod +x /tmp/01-install-prerequisites.sh && /tmp/01-install-prerequisites.sh

The script installs:

• git, curl, unzip, ca-certificates
• Bun (JavaScript runtime)
• GitHub CLI (gh)
• git-lfs (large file support)
• Claude Code CLI

Step 5: Install Docker Desktop (Optional)

# Download and run Docker installer
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/notchrisgroves/ia-framework/main/setup/windows/04-install-docker.ps1" -OutFile "$env:TEMP\04-install-docker.ps1"; & "$env:TEMP\04-install-docker.ps1"

The script downloads Docker Desktop (~500MB) with a progress bar. After installation completes, restart Windows. Then configure WSL Integration:

• Launch Docker Desktop
• Settings → Resources → WSL Integration
• Enable toggle for "Ubuntu"
• Click "Apply & Restart"

Verify in WSL terminal:

wsl
docker --version
docker ps

Step 6: Download Framework

Open a WSL terminal and download the framework as a ZIP file:

# Open WSL terminal
wsl

# Download framework as ZIP
curl -fsSL https://github.com/notchrisgroves/ia-framework/archive/refs/heads/main.zip -o ~/ia-framework.zip

# Extract
unzip ~/ia-framework.zip -d ~/

# Rename to standard directory name
mv ~/ia-framework-main ~/ia-framework

# Clean up ZIP
rm ~/ia-framework.zip

# Navigate to framework
cd ~/ia-framework

Step 7: Launch Claude Code

cd ~/ia-framework
claude

Claude Code starts in the framework directory, ready for setup.

Step 8: Run /setup

Inside Claude Code, give this prompt:

run the setup command from commands/setup.md

Claude will:

• Detect your platform
• Validate framework structure
• Create symlinks from ~/.claude/ to framework
• Configure .env from template
• Set privacy preferences
• Install dependencies
• Run health checks

Linux users need to install prerequisites before downloading the framework.

Step 1: Install Prerequisites

# Download and run prerequisites script
curl -fsSL https://raw.githubusercontent.com/notchrisgroves/ia-framework/main/setup/linux/01-install-prerequisites.sh -o /tmp/01-install-prerequisites.sh
chmod +x /tmp/01-install-prerequisites.sh
/tmp/01-install-prerequisites.sh

The script installs:

• git, curl, unzip, ca-certificates
• Bun (JavaScript runtime)
• GitHub CLI (gh)
• git-lfs (large file support)
• Claude Code CLI

Step 2: Install Docker Engine (Optional)

Docker is optional but recommended for containerized tools:

# Download and run Docker installation script
curl -fsSL https://raw.githubusercontent.com/notchrisgroves/ia-framework/main/setup/linux/02-install-docker.sh -o /tmp/02-install-docker.sh
chmod +x /tmp/02-install-docker.sh
/tmp/02-install-docker.sh

After installation, log out and back in for docker group changes to take effect (or run newgrp docker for current session).

Step 3: Download Framework

Option A: Download as ZIP (No git required)

# Download framework as ZIP
curl -fsSL https://github.com/notchrisgroves/ia-framework/archive/refs/heads/main.zip -o ~/ia-framework.zip

# Extract
unzip ~/ia-framework.zip -d ~/

# Rename to standard directory name
mv ~/ia-framework-main ~/ia-framework

# Clean up
rm ~/ia-framework.zip

Option B: Git Clone (If you prefer version control)

# Clone the repository
git clone https://github.com/notchrisgroves/ia-framework.git ~/ia-framework

Step 4: Launch Claude Code

cd ~/ia-framework
claude

Step 5: Run /setup

Inside Claude Code, give this prompt:

run the setup command from commands/setup.md

Claude handles the rest automatically.

macOS users need Homebrew and prerequisites before downloading the framework.

Step 1: Install Prerequisites

# Download and run prerequisites script
curl -fsSL https://raw.githubusercontent.com/notchrisgroves/ia-framework/main/setup/macos/01-install-prerequisites.sh -o /tmp/01-install-prerequisites.sh
chmod +x /tmp/01-install-prerequisites.sh
/tmp/01-install-prerequisites.sh

The script installs:

• Homebrew (if not present)
• git, bun, GitHub CLI, git-lfs via Homebrew
• Claude Code CLI
• Configures PATH for Apple Silicon

Step 2: Install Docker (Optional)

Docker is optional but recommended:

# Download and run Docker installation script
curl -fsSL https://raw.githubusercontent.com/notchrisgroves/ia-framework/main/setup/macos/02-install-docker.sh -o /tmp/02-install-docker.sh
chmod +x /tmp/02-install-docker.sh
/tmp/02-install-docker.sh

The script offers two options:

Option 1: Docker Desktop (GUI) - Full application with dashboard

Option 2: Colima (CLI) - Command-line only, open-source, no license restrictions

Step 3: Download Framework

Option A: Download as ZIP (No git required)

# Download framework as ZIP
curl -fsSL https://github.com/notchrisgroves/ia-framework/archive/refs/heads/main.zip -o ~/ia-framework.zip

# Extract
unzip ~/ia-framework.zip -d ~/

# Rename to standard directory name
mv ~/ia-framework-main ~/ia-framework

# Clean up
rm ~/ia-framework.zip

Option B: Git Clone (If you prefer version control)

# Clone the repository
git clone https://github.com/notchrisgroves/ia-framework.git ~/ia-framework

Step 4: Launch Claude Code

cd ~/ia-framework
claude

Step 5: Run /setup

Inside Claude Code, give this prompt:

run the setup command from commands/setup.md

Claude handles the rest automatically.

OpenRouter provides access to multiple AI models from one platform. The framework uses it for multi-model QA and image generation.

Getting Your API Key:

1. Visit https://openrouter.ai/keys
2. Create an account or sign in
3. Add credits (minimum $5)
4. Create an API key

Add to .env:

cd ~/ia-framework
nano .env

Add your key:

OPENROUTER_API_KEY=sk-or-v1-your-key-here

Save and exit (Ctrl+X, Y, Enter).

Instead of using a Claude Pro/Max subscription, you can configure Claude Code to route all requests through OpenRouter.

Why OpenRouter?

• Pay-per-use pricing (no monthly subscription)
• Access to multiple AI models from one platform
• Better for testing or intermittent use

Method 1: Shell Profile (Global)

Add to your shell profile (~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish):

# Use OpenRouter for Claude Code
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
export ANTHROPIC_API_KEY=""  # Important: explicitly empty

# Your OpenRouter API key
export OPENROUTER_API_KEY=sk-or-v1-your-key-here

Then reload: source ~/.bashrc (or your shell config file)

Method 2: Project Settings File (Per-Project)

Create .claude/settings.local.json in your project root:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "sk-or-v1-your-key-here",
    "ANTHROPIC_API_KEY": ""
  }
}

Switching back to Claude Pro/Max is simple:

If You Configured Shell Profile:

Edit your shell configuration file and remove or comment out these lines:

# Delete or comment out these lines:
# export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
# export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
# export ANTHROPIC_API_KEY=""
# export OPENROUTER_API_KEY=sk-or-v1-your-key-here

Then reload: source ~/.bashrc (or your shell config file)

If You Configured Project Settings File:

rm .claude/settings.local.json

Claude Code will automatically fall back to your Claude Pro/Max subscription.

GitHub CLI provides secure authentication for git operations.

Authenticate with GitHub CLI:

gh auth login

Follow the prompts to authenticate.

Get Your Token:

gh auth token

Add to .env:

cd ~/ia-framework
nano .env

Add your token:

GITHUB_TOKEN=ghp_your_token_here

Context7 provides up-to-date library documentation lookup.

Getting Your API Key:

1. Visit https://context7.com
2. Sign up for an account
3. Navigate to API keys section
4. Create a new API key

Add to .env:

cd ~/ia-framework
nano .env

Add your key:

CONTEXT7_API_KEY=your-context7-key-here

If you're using Anthropic API instead of Claude Pro/Max subscription:

Getting Your API Key:

1. Visit https://console.anthropic.com/
2. Sign in or create an account
3. Navigate to API keys
4. Create a new API key

Add to .env:

cd ~/ia-framework
nano .env

Add your key:

ANTHROPIC_API_KEY=sk-ant-your-key-here

The framework includes a real-time monitoring dashboard with file browser.

First-Time Setup:

Run /mon-setup inside Claude Code to validate dependencies and configure the monitor. This only needs to be done once.

Starting the Monitor:

Inside Claude Code:

/mon-start

Or from terminal:

cd ~/ia-framework

Open your browser to http://localhost:3000

Stopping the Monitor:

/mon-stop

Wispr Flow provides voice-to-text dictation for faster input.

Installation:

1. Visit https://wispr.ai/
2. Download Wispr Flow for your platform
3. Install and run
4. Configure hotkey (default: hold both Shift keys)

Claude doesn't see your CLAUDE.md? Check symlinks:

ls -la ~/.claude/CLAUDE.md  # Must be symlink or file
readlink ~/.claude/CLAUDE.md  # If symlink, must point to valid file
cat ~/.claude/CLAUDE.md | head -5  # Must be readable

Fix broken symlink:

rm ~/.claude/CLAUDE.md
ln -s ~/ia-framework/CLAUDE.md ~/.claude/CLAUDE.md

If bun --version fails after installation:

# Reload shell configuration
source ~/.bashrc   # for bash
source ~/.zshrc    # for zsh

# Or simply close and reopen terminal

Symptom: Files have :Zone.Identifier suffix

Solution: Add to /etc/wsl.conf:

[automount]
options = "metadata,umask=22,fmask=11"

Then restart WSL: wsl --shutdown

Symptom: ping google.com fails

Solution:

sudo rm /etc/resolv.conf
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
sudo chattr +i /etc/resolv.conf

Clean uninstall:

The installer backs up any existing files with .bak extensions. During uninstall, restore those backups so you don't lose your original configuration.

# Restore backed-up files (if they exist)
[ -f ~/.claude/CLAUDE.md.bak ] && mv ~/.claude/CLAUDE.md.bak ~/.claude/CLAUDE.md || rm -f ~/.claude/CLAUDE.md
[ -f ~/.claude/settings.json.bak ] && mv ~/.claude/settings.json.bak ~/.claude/settings.json || rm -f ~/.claude/settings.json
[ -d ~/.claude/commands.bak ] && mv ~/.claude/commands.bak ~/.claude/commands || rm -f ~/.claude/commands
[ -d ~/.claude/agents.bak ] && mv ~/.claude/agents.bak ~/.claude/agents || rm -f ~/.claude/agents

# Remove framework directory
rm -rf ~/ia-framework

What happens:

• If you had existing files before installing, they're restored from .bak backups
• If it was a clean install, the symlinks are just removed
• Claude Code's files (projects, todos, history) are always preserved

Complete removal:

To also remove Claude Code entirely:

rm -rf ~/.claude

If something goes wrong, ask Claude:

Help me troubleshoot my IA framework setup

Claude will check your installation, verify symlinks, and diagnose issues.

Other resources:

• GitHub Issues: https://github.com/notchrisgroves/ia-framework/issues
• Documentation: See docs/ directory for architecture details