Claude Code Setup

This guide covers installing Claude Code and configuring it for optimal use in a WSL2 development environment.

1. Prerequisites

Claude Code requires Node.js 20 or later. Ensure Node.js is installed before proceeding.

2. Install Node.js

2.1. Option 1: NodeSource repository (recommended)

Install Node.js 20.x from NodeSource:

# Install NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# Install Node.js
sudo apt install nodejs -y

Verify the installation:

node --version
npm --version

2.2. Option 2: Node Version Manager (nvm)

If you need to manage multiple Node.js versions:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# Reload shell configuration
source ~/.bashrc

# Install and use Node.js 20
nvm install 20
nvm use 20

3. Install Claude Code

Install Claude Code globally using npm:

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

Verify the installation:

claude --version

4. Configure Claude Code

4.1. Create settings directory

mkdir -p ~/.claude

4.2. Configure permissions

Create the settings file with recommended permissions for development:

cat > ~/.claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "WebSearch",
      "WebFetch",

      "Bash(ls:*)",
      "Bash(cat:*)",
      "Bash(head:*)",
      "Bash(tail:*)",
      "Bash(find:*)",
      "Bash(grep:*)",
      "Bash(wc:*)",
      "Bash(tree:*)",
      "Bash(pwd)",
      "Bash(which:*)",

      "Bash(git status:*)",
      "Bash(git log:*)",
      "Bash(git diff:*)",
      "Bash(git show:*)",
      "Bash(git branch:*)",
      "Bash(git remote:*)",
      "Bash(git ls-files:*)",

      "Bash(java -version:*)",
      "Bash(java --version:*)",
      "Bash(mvn -version:*)",
      "Bash(mvn --version:*)",
      "Bash(mvn dependency:tree:*)",
      "Bash(mvn help:*)",

      "Bash(docker ps:*)",
      "Bash(docker images:*)",
      "Bash(kubectl get:*)",
      "Bash(kubectl describe:*)"
    ],

    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./**/*.pem)",
      "Read(./**/*.key)",

      "Bash(rm -rf:*)",
      "Bash(sudo:*)"
    ],

    "defaultMode": "default"
  },

  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "30000",
    "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1"
  }
}
EOF
Section Purpose

allow

Commands that run without prompting. Includes read-only filesystem operations, git inspection, and version checks.

deny

Commands that are always blocked. Protects sensitive files and prevents dangerous operations.

defaultMode

Default permission mode for new sessions.

This configuration auto-approves read-only operations whilst requiring confirmation for file writes, commits, and builds. Adjust based on your security requirements.

4.3. Create CLAUDE.md for WSL2

Create a project-level or global CLAUDE.md file that instructs Claude Code about the WSL2 environment:

cat > ~/.claude/CLAUDE.md << 'EOF'
# WSL2 Development Environment

This is a WSL2 Ubuntu environment running on Windows.

## Critical Rules

- Use Linux commands only (not Windows commands)
- Use forward slashes for paths (/)
- Use LF line endings, never CRLF
- Shell is Bash

## Command Equivalents

| Avoid (Windows) | Use (Linux) |
|-----------------|-------------|
| `dir`           | `ls -la`    |
| `type`          | `cat`       |
| `copy`          | `cp`        |
| `move`          | `mv`        |
| `del`           | `rm`        |
| `findstr`       | `grep`      |

## Filesystem Performance

- Fast: `~/` (native Linux filesystem)
- Slow: `/mnt/c/` (Windows mount - avoid for development)

## Development Stack

- Java 21 (OpenJDK)
- Maven
- Git with SSH
- Node.js 20+
EOF

5. Using Claude Code

5.1. Start a session

Navigate to your project directory and start Claude Code:

cd ~/dev/ems/admin-service
claude

5.2. Permission modes

Cycle through permission modes using Shift+Tab:

  1. normal-mode - Standard prompts for write operations

  2. auto-accept edit on - Auto-approve all operations

  3. plan mode on - Read-only exploration

5.3. Check current permissions

View configured permissions:

claude /permissions

6. Integration with IDEs

6.1. VS Code

When using VS Code with Remote-WSL, Claude Code runs in the WSL2 terminal:

  1. Open VS Code

  2. Connect to WSL2 (Ctrl+Shift+P → "WSL: Connect to WSL")

  3. Open the integrated terminal (Ctrl+`)

  4. Run claude in the terminal

6.2. IntelliJ IDEA

IntelliJ’s terminal can be configured to use WSL2:

  1. Open IntelliJ Settings (Ctrl+Alt+S)

  2. Navigate to Tools → Terminal

  3. Set Shell path to: wsl.exe

  4. Open a new terminal tab

  5. Run claude in the terminal

7. Configuration file locations

File Location

Global settings

~/.claude/settings.json

Global CLAUDE.md

~/.claude/CLAUDE.md

Project settings (shared)

.claude/settings.json

Project settings (local)

.claude/settings.local.json

Project CLAUDE.md

CLAUDE.md (in project root)

Project-level settings override global settings. Use .claude/settings.local.json for personal preferences that should not be committed to version control.

8. Troubleshooting

8.1. Claude Code not found

If claude command is not found after installation:

# Check npm global bin location
npm config get prefix

# Add to PATH if needed
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc
source ~/.bashrc

8.2. Permission issues

If you encounter permission errors running npm global installs:

# Fix npm global directory permissions
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$PATH:$HOME/.npm-global/bin"' >> ~/.bashrc
source ~/.bashrc

# Reinstall Claude Code
npm install -g @anthropic-ai/claude-code

9. Next steps

Proceed to VS Code Integration to configure VS Code for WSL2 development.