AI CLI Developer Setup

What Breaks on Native Windows

Running AI dev tools directly on Windows (via PowerShell or cmd) leads to a cascade of subtle, hard-to-debug problems:

WSL2 Architecture

WSL2 runs a real Linux kernel inside a lightweight virtual machine managed by Windows. It's not emulation — it's actual Linux.

System Requirements

Key Benefits of WSL2

Step 1: Install WSL

Open PowerShell or Windows Terminal as Administrator (right-click → "Run as administrator") and run:

wsl --install

This single command does everything:

• Enables the WSL feature
• Enables the Virtual Machine Platform
• Downloads the latest Linux kernel
• Sets WSL2 as the default version
• Installs Ubuntu (the default distribution)

Step 2: Choose Your Distribution

Ubuntu is installed by default and is the best choice for beginners. If you want a different distro, you can see available options:

# List available distributions
wsl --list --online

# Install a specific one (example)
wsl --install -d Ubuntu-24.04

Step 3: Get Windows Terminal

Windows Terminal is the best way to use WSL. It supports tabs, split panes, and automatic WSL integration.

Install it from the Microsoft Store or via winget:

# Install Windows Terminal (from PowerShell)
winget install Microsoft.WindowsTerminal

Once installed, Ubuntu will appear as a dropdown option in Windows Terminal automatically.

Step 4: First Launch — Creating Your User

After reboot, Ubuntu launches automatically (or open it from Windows Terminal). You'll be prompted to create a Unix username and password:

Installing, this may take a few minutes...
Please create a default UNIX user account.
The username does not need to match your Windows username.
Enter new UNIX username: yourname
New password: (type your password — it won't show)
Retype new password:
passwd: password updated successfully
Installation successful!

Step 5: Update Everything

First thing to do in any fresh Linux install: update the package lists and upgrade installed packages.

# Update package lists
sudo apt update

# Upgrade all installed packages
sudo apt upgrade -y

# Install essential build tools
sudo apt install -y build-essential curl wget git unzip

What each package gives you:

Step 6: Configure Git

Tell Git who you are. This information appears in every commit you make.

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

# Use 'main' as the default branch name
git config --global init.defaultBranch main

# Set default editor (nano is easiest for beginners)
git config --global core.editor nano

# Enable colored output
git config --global color.ui auto

# Verify your config
git config --global --list

Step 7: Verify Everything Works

Run these commands to confirm your WSL2 environment is healthy:

# Confirm you're running WSL2 (not WSL1)
wsl.exe -l -v
# Should show VERSION 2 next to your distro

# Check your Linux version
lsb_release -a
# Should show Ubuntu with a version number

# Verify git
git --version

# Check you're in your home directory
pwd
# Should show /home/yourname

# Verify internet connectivity
curl -s https://httpbin.org/ip | head -5

Where Are My Files?

Understanding the filesystem is critical. WSL2 has its own Linux filesystem, but it can also access Windows files:

# Create a projects directory in your Linux home
mkdir -p ~/projects
cd ~/projects

# Access your Windows Desktop (if needed)
ls /mnt/c/Users/$USER/Desktop/

# Open current WSL directory in Windows Explorer
explorer.exe .

Git — Beyond the Basics

Git comes pre-installed with Ubuntu, but you need to configure it properly for WSL. These settings prevent common cross-platform headaches.

# Identity (required for commits)
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

# Line ending behavior (critical for WSL)
git config --global core.autocrlf false
git config --global core.eol lf

# Modern defaults
git config --global init.defaultBranch main
git config --global color.ui auto
git config --global pull.rebase false

# Credential storage (keeps you logged in)
git config --global credential.helper store

# Verify everything
git config --global --list

GitHub CLI (gh)

The GitHub CLI lets you create repos, open PRs, manage issues, and authenticate — all from the terminal. It's the fastest way to connect Git to your GitHub account.

1. Install GitHub CLI

   Add the official repository and install:

   # Add GitHub CLI repository
   (type -p wget >/dev/null || sudo apt install wget -y) \
     && sudo mkdir -p -m 755 /etc/apt/keyrings \
     && wget -qO- https://cli.github.com/packages/githubcli-archive-keyring.gpg \
     | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg >/dev/null \
     && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
     && echo "deb [arch=$(dpkg --print-architecture) \
     signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] \
     https://cli.github.com/packages stable main" \
     | sudo tee /etc/apt/sources.list.d/github-cli.list >/dev/null \
     && sudo apt update \
     && sudo apt install gh -y

2. Authenticate with GitHub

   Log in using the browser-based OAuth flow:

   gh auth login

   Choose: GitHub.com → HTTPS → Login with a web browser. Copy the one-time code, open the URL in your browser, paste the code, and authorize.

3. Verify authentication

   # Check login status
   gh auth status
   
   # Test by listing your repos
   gh repo list --limit 5

Node.js via nvm

nvm (Node Version Manager) lets you install and switch between multiple Node.js versions without root access. It installs everything to your home directory.

1. Install nvm

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

2. Reload your shell

   # Pick one depending on your shell
   source ~/.bashrc    # for bash
   source ~/.zshrc     # for zsh

3. Install the latest LTS version

   # Install latest Long Term Support release
   nvm install --lts
   
   # Set it as your default
   nvm alias default lts/*
   
   # Verify
   node --version   # Should show v20.x or v22.x
   npm --version    # Should show 10.x+

# Create .nvmrc in your project
echo "20" > .nvmrc

# Later, in that project directory:
nvm use
# Found '/home/you/projects/myapp/.nvmrc' with version <20>
# Now using node v20.x.x

Python

Ubuntu ships with Python 3, but you'll often need a newer version or multiple versions. There are two solid approaches:

# Add the deadsnakes PPA
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update

# Install Python 3.12 (or whatever version you need)
sudo apt install -y python3.12 python3.12-venv python3.12-dev

# Verify
python3.12 --version

# Install build dependencies first
sudo apt install -y make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
  libffi-dev liblzma-dev

# Install pyenv
curl https://pyenv.run | bash

# Add to your shell config (~/.bashrc or ~/.zshrc)
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

# Reload shell
source ~/.bashrc

# Install and set a Python version
pyenv install 3.12
pyenv global 3.12

# Verify
python --version

Windows PATH Leaking into WSL

Symptoms of PATH leaking:

• which node shows /mnt/c/Program Files/nodejs/node instead of an nvm path
• Commands run painfully slow (crossing the filesystem boundary)
• echo $PATH is hundreds of characters long, full of /mnt/c/... entries
• Wrong tool versions are picked up silently

The fix: Disable Windows PATH injection in /etc/wsl.conf:

# Create or edit /etc/wsl.conf
sudo nano /etc/wsl.conf

Add these lines:

# /etc/wsl.conf
[interop]
appendWindowsPath = false

Then restart WSL from PowerShell:

# Run in PowerShell (not in WSL)
wsl --shutdown

# Reopen Ubuntu from Windows Terminal

# Selectively add back useful Windows commands
export PATH="$PATH:/mnt/c/Windows/System32"
export PATH="$PATH:/mnt/c/Users/$USER/AppData/Local/Programs/Microsoft VS Code/bin"

CRLF vs LF Explained

Every text file uses invisible characters to mark the end of each line. The problem? Windows and Linux use different ones.

What goes wrong when CRLF sneaks into Linux files:

Git Configuration

Git has a setting called core.autocrlf that controls automatic line ending conversion. Here are your options:

# Best for WSL: no conversion at all
git config --global core.autocrlf false
git config --global core.eol lf

# Alternative: convert CRLF to LF on commit only
# git config --global core.autocrlf input

.gitattributes — The Definitive Fix

While core.autocrlf is a per-machine setting, .gitattributes travels with the repository. It ensures every contributor uses the same line ending rules regardless of their OS or Git config.

# Auto-detect text files and normalize to LF
* text=auto eol=lf

# Explicitly declare text files
*.js    text eol=lf
*.ts    text eol=lf
*.jsx   text eol=lf
*.tsx   text eol=lf
*.json  text eol=lf
*.md    text eol=lf
*.html  text eol=lf
*.css   text eol=lf
*.yml   text eol=lf
*.yaml  text eol=lf
*.sh    text eol=lf
*.py    text eol=lf
*.rb    text eol=lf
*.sql   text eol=lf
*.xml   text eol=lf
*.env   text eol=lf

# Declare binary files (never convert)
*.png   binary
*.jpg   binary
*.jpeg  binary
*.gif   binary
*.ico   binary
*.woff  binary
*.woff2 binary
*.ttf   binary
*.eot   binary
*.pdf   binary
*.zip   binary

If your repo already has CRLF files, you need to renormalize after adding .gitattributes:

# Renormalize all files after adding .gitattributes
git add --renormalize .
git commit -m "Normalize line endings to LF"

dos2unix — Fix Existing Files

When CRLF has already crept into your files, dos2unix converts them in place.

# Install dos2unix
sudo apt install -y dos2unix

# Convert a single file
dos2unix script.sh

# Convert multiple files
dos2unix *.sh *.py *.js

# Convert all text files in a directory recursively
find . -type f -name "*.sh" -exec dos2unix {} +

How to detect CRLF in files:

# The `file` command shows line ending type
file script.sh
# script.sh: Bash script, ASCII text, with CRLF line terminators
#                                    ^^^^^^^^^^^^^^^^^^^^^^^^
# If it says "CRLF" — that's your problem

# Show CRLF characters as ^M in a file
cat -A script.sh | head -5
# Lines ending with ^M$ have CRLF
# Lines ending with just $ are LF (correct)

BOM (Byte Order Mark)

The Byte Order Mark is a hidden 3-byte sequence (EF BB BF) that some Windows editors (notably old versions of Notepad) add to the beginning of UTF-8 files. It's invisible in most editors but causes real problems:

• Shell scripts fail: the shebang (#!/bin/bash) isn't the first bytes anymore
• JSON parsing breaks: the BOM isn't valid JSON
• PHP outputs a blank line before any content
• YAML and config files may silently misparse

# Detect BOM by inspecting the first bytes
hexdump -C script.sh | head -1
# If the first three bytes are: ef bb bf — that's a BOM
# Example output with BOM:
# 00000000  ef bb bf 23 21 2f 62 69  6e 2f 62 61 73 68 0a  |...#!/bin/bash.|
#           ^^^^^^^^ BOM bytes

# Remove BOM with sed
sed -i '1s/^\xEF\xBB\xBF//' file.txt

# Or use dos2unix (handles BOM too)
dos2unix --remove-bom file.txt

.editorconfig — Prevent Issues at the Source

EditorConfig is a cross-editor standard that configures line endings, indentation, and encoding before files are even saved. Most editors (VS Code, JetBrains, Vim, Sublime) support it natively or via plugin.

# EditorConfig — https://editorconfig.org
root = true

# Apply to all files
[*]
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
charset = utf-8
indent_style = space
indent_size = 2

# Python: 4-space indent
[*.py]
indent_size = 4

# Makefiles: must use tabs
[Makefile]
indent_style = tab

# Markdown: trailing whitespace is intentional (line breaks)
[*.md]
trim_trailing_whitespace = false

Drop this file in your project root alongside .gitattributes. Together, they form a two-layer defense:

Installation

There are two ways to install Claude Code. Both require Node.js 18+.

curl -fsSL https://claude.ai/install.sh | sh

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

# Verify the installation
claude --version

# Check that everything is working
claude doctor

Authentication

Claude Code supports two authentication methods:

# Add to ~/.bashrc or ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-..."

# Reload shell config
source ~/.bashrc

First Run

Navigate to a project directory and launch Claude Code:

# Navigate to your project
cd ~/projects/my-app

# Launch Claude Code
claude

On first run, you'll authenticate (browser opens automatically for OAuth). Then you're in an interactive session where you can type natural language requests.

Permission Modes

Claude Code has three permission modes that control how much autonomy the AI has. Cycle between them with Shift+Tab.

CLAUDE.md — Your Project Instruction File

CLAUDE.md is a special file that Claude Code reads automatically when you start a session. It tells the AI about your project: what it is, how it's structured, what conventions to follow, and what commands to run.

# My Web App

## Project Overview
A React + TypeScript SPA with a Node.js/Express backend.
Uses PostgreSQL for data, Redis for caching.

## Tech Stack
- Frontend: React 18, TypeScript, Vite, Tailwind CSS
- Backend: Node.js 20, Express, Prisma ORM
- Database: PostgreSQL 15
- Testing: Vitest (unit), Playwright (e2e)

## Commands
- `npm run dev` — Start dev server (frontend + backend)
- `npm test` — Run unit tests
- `npm run lint` — Run ESLint + Prettier check
- `npm run build` — Production build

## Conventions
- Use functional components with hooks (no class components)
- All API routes go in `src/api/routes/`
- Database migrations in `prisma/migrations/`
- Use named exports, not default exports
- Commit messages: conventional commits format

## Important Notes
- Never modify `prisma/schema.prisma` without running
  `npx prisma migrate dev` afterward
- The `.env` file is gitignored — see `.env.example`

Best practices for CLAUDE.md:

• Keep it under 300 lines — Claude reads this every session, so conciseness matters
• Focus on what's non-obvious: conventions, gotchas, project-specific patterns
• Include the commands Claude will need: test, lint, build, deploy
• List the tech stack so Claude knows what frameworks/versions to target
• Update it as your project evolves — treat it like living documentation

# Generate a starter CLAUDE.md for your project
cd ~/projects/my-app
claude
# Then type:
/init

Cost Awareness

Claude Code uses AI models that cost money to run, whether through a subscription or API usage. Understanding costs helps you budget effectively.

# Check your current session cost
/cost

# Example output:
# Total cost: $0.42
# Input tokens: 45,230
# Output tokens: 12,847

Installation

Codex CLI is installed via npm, just like Claude Code. You need Node.js 18+ (which you already have if you followed the earlier sections).

# Install Codex CLI globally
npm install -g @openai/codex

# Verify installation
codex --version

Authentication

Codex CLI needs to connect to OpenAI's API. There are two ways to authenticate:

# Add to ~/.bashrc or ~/.zshrc
export OPENAI_API_KEY="sk-..."

# Reload shell config
source ~/.bashrc

Basic Usage

Codex CLI has two primary modes: interactive and non-interactive.

# Interactive mode — opens a REPL session
codex

# Non-interactive — execute a single task and exit
codex exec "add error handling to the login function"

# Run with a specific model
codex --model o4-mini

# Quiet mode — less output, just results
codex --quiet exec "fix the failing test in auth.test.js"

Codex CLI also supports three approval modes, similar to Claude Code's permission system:

Claude Code vs. Codex CLI

Both are excellent AI coding agents, but they have different strengths and philosophies. Here's an honest comparison to help you decide when to reach for each one.

Zsh Installation

Bash is the default shell in Ubuntu, but Zsh is a more feature-rich alternative with better autocompletion, theming, and plugin support. Most modern developer setups use Zsh.

# Install Zsh
sudo apt install -y zsh

# Verify installation
zsh --version

# Set Zsh as your default shell
chsh -s $(which zsh)

# Log out and back in (or restart your terminal)
# Verify it took effect
echo $SHELL
# Should output: /usr/bin/zsh

Oh My Zsh

Oh My Zsh is a community-driven framework for managing your Zsh configuration. It provides themes, plugins, and sensible defaults that make Zsh immediately more useful.

# Install Oh My Zsh (downloads and sets up automatically)
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

After installation, Oh My Zsh gives you:

Essential Plugins

These two third-party plugins are the most impactful upgrades you can make to your shell. They need to be installed separately, then enabled in .zshrc.

# Install
git clone https://github.com/zsh-users/zsh-autosuggestions \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

# Install
git clone https://github.com/zsh-users/zsh-syntax-highlighting \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting

After installing both, enable them in your .zshrc plugins array:

# In ~/.zshrc, find the plugins=(...) line and update it:
plugins=(
  git
  sudo
  z
  zsh-autosuggestions
  zsh-syntax-highlighting   # Must be LAST in the list
)

# Reload your config to activate
source ~/.zshrc

Starship Prompt

Starship is a modern, cross-shell prompt that's fast, highly customizable, and looks great out of the box. It shows useful info like Git branch, Node version, Python virtualenv, and command duration — all without slowing down your terminal.

# Install Starship
curl -sS https://starship.rs/install.sh | sh

# Add to the END of ~/.zshrc
eval "$(starship init zsh)"

# Reload
source ~/.zshrc

Starship works immediately with zero configuration, but you can customize it by creating a config file:

# Create Starship config directory and file
mkdir -p ~/.config
touch ~/.config/starship.toml

# Minimal, clean prompt config
format = """
$directory\
$git_branch\
$git_status\
$nodejs\
$python\
$cmd_duration\
$line_break\
$character"""

[directory]
truncation_length = 3
truncate_to_repo = true

[git_branch]
symbol = " "

[git_status]
ahead = "+"
behind = "-"
diverged = "+-"

[nodejs]
symbol = " "
detect_files = ["package.json"]

[python]
symbol = " "

[cmd_duration]
min_time = 2000   # Only show for commands taking 2+ seconds
format = " took [$duration]($style)"

[character]
success_symbol = "[>](bold green)"
error_symbol = "[>](bold red)"

.zshrc Tips

Your ~/.zshrc is your shell's configuration file. It runs every time you open a terminal. Here are some useful additions:

# Modern replacements for classic tools
alias cat="batcat --style=plain"    # bat: cat with syntax highlighting
alias ls="eza --icons --group-directories-first"  # eza: modern ls
alias ll="eza -la --icons --group-directories-first --git"
alias find="fdfind"                 # fd: intuitive find replacement
alias grep="rg"                     # ripgrep: fast grep

# Quick navigation
alias ..="cd .."
alias ...="cd ../.."
alias proj="cd ~/projects"

# Git shortcuts (beyond what oh-my-zsh provides)
alias gs="git status"
alias gl="git log --oneline -20"
alias gd="git diff"

# History settings — add to ~/.zshrc
HISTSIZE=50000              # Commands to keep in memory
SAVEHIST=50000              # Commands to save to file
HISTFILE=~/.zsh_history

setopt HIST_IGNORE_DUPS     # Don't store duplicate commands
setopt HIST_IGNORE_SPACE    # Don't store commands starting with space
setopt SHARE_HISTORY        # Share history between terminals
setopt HIST_REDUCE_BLANKS   # Remove extra blanks from commands
setopt INC_APPEND_HISTORY   # Write immediately, don't wait for exit

# nvm is slow to load (~200-400ms). Lazy-load it instead.
# Replace the default nvm init block with:

export NVM_DIR="$HOME/.nvm"
# This loads nvm only when you first call node, npm, npx, or nvm
lazy_load_nvm() {
  unset -f node npm npx nvm
  [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
}
node()  { lazy_load_nvm; node  "$@"; }
npm()   { lazy_load_nvm; npm   "$@"; }
npx()   { lazy_load_nvm; npx   "$@"; }
nvm()   { lazy_load_nvm; nvm   "$@"; }

Nerd Fonts

Starship, Powerlevel10k, and many CLI tools use special icons (glyphs) that aren't in standard fonts. Nerd Fonts are patched fonts that include thousands of these icons alongside normal characters.

The Essential Toolkit

Each of these tools is a drop-in upgrade for a common task. Install them all or pick the ones that fit your workflow. They're sorted from "install this first" to "nice to have".

# Install lazygit
sudo add-apt-repository ppa:lazygit-team/daily
sudo apt update
sudo apt install -y lazygit

# Install fzf
sudo apt install -y fzf

# Example: fuzzy-find a file
vim $(fzf)

# Install ripgrep
sudo apt install -y ripgrep

# Example: search for a function
rg "function handleClick" --type js

# Install fd
sudo apt install -y fd-find

# The binary is 'fdfind' — alias it
alias fd="fdfind"

# Example: find all .ts files
fd -e ts

# Install bat
sudo apt install -y bat

# The binary is 'batcat' — alias it
alias bat="batcat"

# Example: view a file with highlighting
bat src/index.ts

# Install eza
sudo apt install -y eza

# Example: list with icons and git info
eza -la --icons --git

# Install via install script
curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh

# Add to ~/.zshrc
eval "$(zoxide init zsh)"

# Usage: jump by partial name
z proj        # Jumps to ~/projects
z my-app      # Jumps to ~/projects/my-app

# Install via cargo (requires Rust)
cargo install mcfly

# Add to ~/.zshrc
eval "$(mcfly init zsh)"

# Install mc
sudo apt install -y mc

# Launch it
mc

# Install btop
sudo apt install -y btop

# Launch it
btop

# Install tldr
sudo apt install -y tldr

# Update the page cache
tldr --update

# Example: quick help for tar
tldr tar

# Install delta
sudo apt install -y git-delta

# Configure git to use delta
git config --global core.pager delta
git config --global interactive.diffFilter "delta --color-only"
git config --global delta.navigate true
git config --global delta.side-by-side true

# Install httpie
sudo apt install -y httpie

# Example: GET request
http httpbin.org/get

# Example: POST JSON
http POST api.example.com/users name=John

Quick Install

Install all the apt-based tools in a single command:

# Install all apt-based CLI power tools at once
sudo apt install -y \
  fzf \
  ripgrep \
  fd-find \
  bat \
  eza \
  mc \
  btop \
  tldr \
  git-delta \
  httpie

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Then install cargo-based tools
cargo install mcfly zoxide

Shell Integration Cheat Sheet

After installing the tools, add these lines to your ~/.zshrc to wire everything together:

# ===== Aliases for tools with different binary names =====
alias bat="batcat"
alias fd="fdfind"

# ===== Modern tool aliases =====
alias cat="batcat --style=plain"
alias ls="eza --icons --group-directories-first"
alias ll="eza -la --icons --group-directories-first --git"

# ===== Tool initialization =====
eval "$(zoxide init zsh)"         # Smarter cd
eval "$(mcfly init zsh)"          # AI-powered history
eval "$(starship init zsh)"       # Starship prompt (keep this last)

/mnt/c Performance Penalty

# DON'T do this
cd /mnt/c/Users/YourName/Documents/projects
npm install   # Takes 2-3 minutes
git status    # Takes 5-10 seconds

# DO this instead
cd ~/projects/my-app
npm install   # Takes 15-20 seconds
git status    # Instant

# Test it yourself — create a test project in both locations

# On /mnt/c (Windows filesystem)
cd /mnt/c/Users/YourName/Desktop
mkdir test-speed && cd test-speed
time npm init -y && time npm install express
# Real time: ~45 seconds

# On ~ (Linux filesystem)
cd ~
mkdir test-speed && cd test-speed
time npm init -y && time npm install express
# Real time: ~4 seconds

File Permissions

By default, chmod has no effect on files stored in /mnt/c/ because NTFS doesn't understand Unix permissions. This breaks SSH keys, scripts, and any tool that checks file modes.

Solution: Enable metadata support in /etc/wsl.conf so WSL can store Unix permissions alongside NTFS files:

# Create or edit /etc/wsl.conf
sudo nano /etc/wsl.conf

# Add these lines:
[automount]
enabled = true
options = "metadata,umask=22,fmask=11"
mountFsTab = false

Memory Limits

WSL2 is hungry. By default, it claims 50% of your total RAM or 8 GB (whichever is less on newer builds). If you have 16 GB of RAM, WSL2 may take 8 GB and leave Windows starving.

Solution: Create a .wslconfig file on the Windows side to set memory limits:

# Create this file at: C:\Users\YourName\.wslconfig
# (Use Notepad or VS Code on Windows)

[wsl2]
memory=8GB
swap=8GB
processors=4

DNS Resolution

DNS failures are one of the most frustrating WSL2 issues. Symptoms: apt update fails, curl can't resolve hosts, npm install times out — but your Windows browser works fine.

Solution A (Windows 11 22H2+): Enable DNS tunneling in .wslconfig:

[wsl2]
dnsTunneling=true

Solution B (manual fix for older versions): Disable auto-generation and set DNS manually:

# Prevent WSL from overwriting resolv.conf
sudo nano /etc/wsl.conf

# Add these lines:
[network]
generateResolvConf = false

# Remove the auto-generated symlink and create a real file
sudo rm /etc/resolv.conf
sudo nano /etc/resolv.conf

# Add reliable public DNS servers:
nameserver 8.8.8.8
nameserver 8.8.4.4
nameserver 1.1.1.1

Networking / localhost

You start a dev server in WSL (like npm run dev on port 3000), open localhost:3000 in your Windows browser, and... nothing loads.

Solution A (Windows 11 22H2+ recommended): Enable mirrored networking mode:

[wsl2]
networkingMode=mirrored

Solution B (find WSL IP manually):

# Find your WSL2 IP address
ip addr show eth0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}'

# Example output: 172.28.160.1
# Use this IP in your Windows browser instead of localhost
# e.g., http://172.28.160.1:3000

# C:\Users\YourName\.wslconfig
[wsl2]
memory=8GB
swap=8GB
processors=4
dnsTunneling=true
networkingMode=mirrored

Forgetting wsl --shutdown

You edit .wslconfig or /etc/wsl.conf, restart your terminal, and nothing changed. That's because config changes require a full WSL restart, not just closing the terminal window.

Solution: Always run this from PowerShell (not from inside WSL) after changing any config:

# Run this in PowerShell (not WSL!)
wsl --shutdown

# Wait a few seconds, then reopen your Ubuntu terminal
# The VM will boot fresh with your new settings

VS Code + WSL Remote

VS Code is the best editor for WSL development. Install it on the Windows side, and it transparently connects to your Linux environment via the WSL extension.

1. Install VS Code on Windows

   Download from code.visualstudio.com. Run the Windows installer normally.

2. Install the WSL extension

   Open VS Code, go to Extensions (Ctrl+Shift+X), search for "WSL" by Microsoft, and install it. This lets VS Code run a server inside WSL.

3. Open projects from WSL

   In your WSL terminal, navigate to any project and type code . to open it in VS Code. The bottom-left corner will show "WSL: Ubuntu" confirming the connection.

   # From your WSL terminal
   cd ~/projects/my-app
   code .

Project Organization

A clean directory structure saves time and prevents confusion. Keep everything on the Linux filesystem.

~                          # /home/yourname (Linux home)
|
+-- projects/               # All your code lives here
|   +-- my-app/             # Individual project repos
|   +-- portfolio/
|   +-- api-server/
|
+-- learning/               # Tutorials, experiments, scratch
|   +-- javascript-30/
|   +-- python-basics/
|
+-- dotfiles/               # Your config files (version controlled)
|   +-- .zshrc
|   +-- .gitconfig
|   +-- setup.sh            # Script to set up a fresh machine
|
+-- .ssh/                   # SSH keys (Linux filesystem only!)

Daily Workflow Example

Here's what a typical AI-assisted development session looks like once everything is set up:

1. Open your terminal

   Launch Windows Terminal. It opens directly into your WSL Ubuntu shell with Zsh, Oh My Zsh, and Starship prompt ready to go.

2. Navigate to your project

   cd ~/projects/my-app

3. Open VS Code

   code .

   VS Code connects to WSL automatically. Your integrated terminal inside VS Code is also running in WSL.

4. Start an AI coding session

   Open the VS Code integrated terminal (or a separate terminal tab) and launch your AI tool:

   # For deep, multi-file work
   claude
   
   # For quick, focused tasks
   codex "add input validation to the signup form"

5. Work with the AI

   Describe what you want in natural language. Review the changes the AI proposes. Accept, reject, or refine. Iterate until it's right.

6. Commit and push

   # Stage and commit your changes
   git add -A
   git commit -m "Add input validation to signup form"
   
   # Push to GitHub as backup
   git push origin main

Git Best Practices for Beginners

Good Git habits make collaboration easier, AI tools more effective, and your future self grateful.

# A good daily Git workflow
git status                        # See what changed
git diff                          # Review the actual changes
git add -A                        # Stage everything
git commit -m "Add user avatar upload"  # Descriptive message
git push origin main              # Back up to GitHub

Learning Path

You've got your environment set up. Now what? Here's a roadmap for building real skills:

1. Build a small project

   Don't just follow tutorials — build something real. A personal website, a CLI tool, a simple API. Use Claude Code or Codex to help, but make sure you understand the code they generate.

2. Learn Git branching

   Move beyond git add/commit/push. Learn git branch, git merge, git rebase, and how to resolve merge conflicts. Try learngitbranching.js.org for interactive practice.

3. Explore MCP integrations

   Claude Code's MCP (Model Context Protocol) lets it connect to databases, APIs, and external tools. Try connecting it to a SQLite database or a REST API to see how it handles real-world data.

4. Compare Claude Code and Codex on the same task

   Give both tools the same prompt on the same project. Compare their approaches, code quality, and speed. You'll develop intuition for when to reach for each tool.

5. Version-control your dotfiles

   Create a ~/dotfiles repo with your .zshrc, .gitconfig, and a setup script. When you get a new machine or reinstall WSL, you can be productive in minutes instead of hours.

Resources

Official documentation, essential repos, and community resources to bookmark.