====== Claude Code on Windows - Installation and Upgrade ======

===== Introduction =====

Claude Code is an AI development assistant created by Anthropic that runs in the terminal. On Windows, Claude Code requires **Windows Subsystem for Linux (WSL)** to function properly.

<note important>
Claude Code does **NOT** run natively on Windows. You must use WSL to create a Linux environment within Windows.
</note>

===== System Requirements =====

  * Windows 10 version 2004+ or Windows 11
  * WSL2 enabled
  * Ubuntu (or other Linux distribution)
  * Node.js 18+ and npm
  * Anthropic account (Claude Max or API key)

===== Step-by-Step Installation =====

==== 1. Enable WSL ====

=== Automatic Installation (Windows 10 2004+ / Windows 11) ===

Open **PowerShell as Administrator** and run:

<code bash>
wsl --install
</code>

This command will:
  * Enable WSL
  * Install Ubuntu as default distribution
  * Restart your computer

=== Manual Installation (older versions) ===

<code bash>
# Enable WSL
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# Enable Virtual Machine Platform
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# Set WSL2 as default version (after restart)
wsl --set-default-version 2
</code>

==== 2. Install Ubuntu ====

=== From Microsoft Store ===
  - Open Microsoft Store
  - Search for "Ubuntu"
  - Install "Ubuntu" (LTS version)
  - Launch Ubuntu from Start Menu
  - Create username and password

=== From Command Line ===
<code bash>
# List available distributions
wsl --list --online

# Install Ubuntu
wsl --install -d Ubuntu
</code>

==== 3. Update Ubuntu System ====

In the Ubuntu terminal, run:

<code bash>
# Update package list
sudo apt update

# Install updates
sudo apt upgrade -y

# Install essential tools
sudo apt install build-essential curl git -y
</code>

==== 4. Install Node.js ====

<code bash>
# Add NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# Install Node.js
sudo apt-get install -y nodejs

# Verify installation
node --version
npm --version
</code>

=== Configure npm for Global Packages ===

<code bash>
# Create directory for global packages
mkdir -p ~/.npm-global

# Configure npm to use this directory
npm config set prefix ~/.npm-global

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

# Reload shell configuration
source ~/.bashrc
</code>

<note warning>
**NEVER** use ''sudo'' with ''npm install'' for global packages! This can cause permission issues and security risks.
</note>

==== 5. Install Claude Code ====

<code bash>
# Install Claude Code globally
npm install -g @anthropic-ai/claude-code

# Verify installation
claude --version
</code>

=== Test Installation ===

<code bash>
# Check if Claude Code is in PATH
which claude

# Should output: /home/username/.npm-global/bin/claude
</code>

==== 6. Authentication ====

=== Option A: Claude Max (Recommended) ===

<code bash>
# Navigate to a project
cd /mnt/c/Users/YourName/Projects/your-project

# Start Claude Code
claude

# Follow OAuth prompts in browser
</code>

=== Option B: API Key ===

<code bash>
# Set API key
export ANTHROPIC_API_KEY=your_key_here

# Add to shell profile
echo 'export ANTHROPIC_API_KEY=your_key' >> ~/.bashrc
source ~/.bashrc
</code>

===== Upgrading Claude Code =====

==== Standard Upgrade Method ====

<code bash>
# Update via npm
npm update -g @anthropic-ai/claude-code

# Or complete reinstall for latest version
npm install -g @anthropic-ai/claude-code
</code>

==== Version Checking ====

<code bash>
# Check current version
claude --version

# Check location
which claude
</code>

==== Automated Upgrade Script ====

<code bash>
#!/bin/bash
# Save as upgrade-claude.sh

echo "🔄 Updating Claude Code..."

# Check current version
echo "Current version:"
claude --version

# Update
npm update -g @anthropic-ai/claude-code

# Check new version
echo "New version:"
claude --version

echo "✅ Upgrade complete!"
</code>

===== Troubleshooting =====

==== Common Issues ====

=== WSL Not Working ===

<code bash>
# Check WSL status
wsl --status

# Update WSL
wsl --update

# Restart WSL
wsl --shutdown
wsl
</code>

=== Node.js Version Conflicts ===

<code bash>
# Check which npm is being used
which npm
which node

# Should show /usr/bin/npm, NOT /mnt/c/...
</code>

=== Permission Errors ===

<code bash>
# Fix npm permissions
sudo chown -R $(whoami) ~/.npm-global
npm config set prefix ~/.npm-global
</code>

=== Performance Issues ===

Work within WSL filesystem, not Windows drives:

<code bash>
# Instead of /mnt/c/Users/...
# Use ~/projects/ or /home/username/projects/

# Copy project to WSL
cp -r /mnt/c/Users/YourName/project ~/project
cd ~/project
</code>

==== Performance Optimizations ====

Create file ''%USERPROFILE%\.wslconfig'':

<code ini>
[wsl2]
memory=8GB
processors=4
swap=2GB
localhostForwarding=true

[experimental]
sparseVhd=true
autoMemoryReclaim=gradual
</code>

===== Basic Usage =====

==== Accessing Windows Projects ====

<code bash>
# Windows files are accessible at /mnt/c/
cd /mnt/c/Users/YourName/Projects

# Or create a new project
mkdir claude-test
cd claude-test

# Initialize a simple project
echo "console.log('Hello Claude!');" > hello.js
</code>

==== Starting Claude Code ====

<code bash>
# Start Claude Code in project
claude

# Basic commands
> "Explain what this JavaScript file does"
> "/init"  # Generate project documentation
> "/help"  # See all available commands
</code>

===== Advanced Configuration =====

==== Global Configuration ====

Create file ''~/.claude.json'':

<code json>
{
  "defaultModel": "claude-sonnet-4",
  "permissions": {
    "allowedTools": ["Edit", "Bash(git*)"],
    "deniedTools": ["Bash(rm*)"]
  },
  "preferences": {
    "autoCompact": true,
    "compactThreshold": 50000
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/Projects"]
    }
  }
}
</code>

==== Environment Variables ====

Add to ''~/.bashrc'':

<code bash>
# Claude Code configuration
export ANTHROPIC_API_KEY=your_key
export CLAUDE_MODEL=claude-sonnet-4
export MCP_DEBUG=false
export NODE_OPTIONS="--max-old-space-size=4096"

# Windows integration
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0
</code>

===== Docker Integration =====

==== Dockerfile for Claude Code ====

<code dockerfile>
FROM node:20-slim

RUN apt-get update && apt-get install -y \
    git \
    curl \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

RUN npm install -g @anthropic-ai/claude-code

WORKDIR /workspace
VOLUME ["/workspace"]

ENV ANTHROPIC_API_KEY=""
CMD ["claude"]
</code>

==== Usage ====

<code bash>
# Build and run
docker build -t claude-code .
docker run -it --rm -v $(pwd):/workspace -e ANTHROPIC_API_KEY=your_key claude-code

# Or use dangerous mode for automation
docker run --rm -v $(pwd):/workspace -e ANTHROPIC_API_KEY=your_key claude-code \
  claude --dangerously-skip-permissions -p "fix all linting errors"
</code>

===== CI/CD Integration =====

==== GitHub Actions Workflow ====

<code yaml>
name: Claude Code CI
on: [push, pull_request]

jobs:
  claude-review:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-node@v3
      with:
        node-version: '20'
    - run: npm install -g @anthropic-ai/claude-code
    - run: claude --dangerously-skip-permissions -p "review this PR"
      env:
        ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
</code>

===== Enterprise Features =====

==== Team Configuration ====

<code json>
{
  "team": {
    "name": "Development Team",
    "defaultModel": "claude-sonnet-4",
    "sharedSettings": {
      "codeStyle": "prettier",
      "testFramework": "jest",
      "linting": "eslint"
    }
  },
  "security": {
    "allowedDomains": ["github.com", "gitlab.com"],
    "restrictedCommands": ["rm", "sudo", "chmod 777"]
  }
}
</code>

===== Useful Resources =====

  * [[https://docs.anthropic.com/en/release-notes/claude-code|Official Claude Code Documentation]]
  * [[https://zebbern.github.io/windows.html|Complete Windows Installation Guide]]
  * [[https://abacus.ai/help/howTo/chatllm|ChatLLM Teams Help Center]]
  * [[https://github.com/microsoft/WSL|WSL on GitHub]]
  * [[https://nodejs.org/en/download/|Node.js Downloads]]

===== FAQ =====

==== Q: Can Claude Code run natively on Windows? ====
A: No, Claude Code requires a Unix-like environment. You must use WSL on Windows.

==== Q: What's the difference between Claude Max and API key? ====
A: Claude Max ($20/month) is more economical for regular users than pay-per-use API pricing.

==== Q: How do I update Claude Code? ====
A: Use ''npm update -g @anthropic-ai/claude-code'' or reinstall with ''npm install -g @anthropic-ai/claude-code''.

==== Q: Why am I getting permission errors? ====
A: Configure npm to use a user-writable directory and never use ''sudo'' with npm global installs.

==== Q: Can I use Claude Code in VS Code? ====
A: Yes, Claude Code integrates with various IDEs and can be used alongside VS Code through the terminal.