Why WSL Is the Right Foundation for Claude Code on Windows
Claude Code is built for Linux-native tooling. Its install scripts, path resolution, and file-watching all assume a POSIX environment. Running it directly on Windows Command Prompt or PowerShell introduces friction that WSL eliminates entirely.
WSL (Windows Subsystem for Linux) gives you a real Ubuntu environment inside Windows with no virtual machine overhead, no dual-boot, and no emulation penalty. From VS Code's perspective, your Linux workspace is a first-class remote connection. From Claude Code's perspective, it is just Linux.
By the end of this guide you will have:
- VS Code installed on Windows and configured to open into WSL by default
- Ubuntu running via WSL with a fully updated package list
- Git and GitHub CLI authenticated to your GitHub account
- Node.js 20 installed inside WSL with a user-level npm directory (no sudo required)
- Claude Code installed, verified, and used to build a Hello World web app
Total time: under an hour on a modern machine with a decent internet connection.
Prerequisites
- A Windows 10 (version 2004 or later) or Windows 11 machine
- Administrator access to your Windows account
- A Claude Pro subscription or Anthropic API credits (required for Claude Code; check billing at console.anthropic.com)
- A GitHub account (or a few minutes to create one at Step 4)
Step 1: Install VS Code
VS Code is your code editor. It runs natively on Windows and connects to your WSL Linux environment via a lightweight remote extension that installs itself automatically.
- Go to https://code.visualstudio.com and download the Windows installer (the large blue button on the homepage).
- Run the installer and accept the defaults.
- On the Select Additional Tasks screen, check Add to PATH. This lets you launch VS Code from any terminal with
code ..
- Complete the install, then launch VS Code at least once so it finishes its first-run setup.
Tip: Pin VS Code to your taskbar. You will open it dozens of times a day.
Step 2: Install WSL (Windows Subsystem for Linux)
WSL gives Claude Code and most developer tooling a proper Linux runtime without leaving Windows.
2a. Open PowerShell as Administrator
Right-click the Start menu and choose Windows Terminal (Admin), or search for PowerShell, right-click it, and select Run as administrator.
2b. Run the install command
wsl --install
This single command turns on the WSL feature, downloads the latest Linux kernel, and installs Ubuntu as the default Linux distribution. No configuration required.
2c. Reboot when prompted
After the install finishes, reboot your machine. Ubuntu launches automatically after reboot and asks you to create a Linux username and password.
Pick a lowercase username with no spaces. The password does not need to match your Windows login, but you will need it for sudo commands, so remember it.
2d. Update Ubuntu
Once inside the Ubuntu terminal, run:
sudo apt update && sudo apt upgrade -y
This downloads the latest package lists and applies all available updates. It takes a few minutes on the first run.
Step 3: Set WSL as the Default Terminal in VS Code
By default, VS Code opens a Windows PowerShell terminal. You want every terminal to drop you directly into Ubuntu.
- Open VS Code.
- Press Ctrl + Shift + P to open the Command Palette.
- Type
Terminal: Select Default Profile and press Enter.
- Select WSL or Ubuntu (WSL) from the list.
Now when you open a terminal in VS Code (Ctrl + backtick), it opens into Ubuntu. Your prompt should look like:
yourname@DESKTOP-XXXXX:~$
If you see a Windows path like C:\Users\..., you are still in PowerShell. Repeat the steps above.
Tip: To open any WSL folder in VS Code, navigate to it in your Ubuntu terminal and type code . (with the period). VS Code installs the WSL Remote extension automatically and reconnects. You will see WSL: Ubuntu in green at the bottom-left corner of the window.
Step 4: Create Your GitHub Account
GitHub is where your code lives. Every project, every experiment, every production deployment starts here.
- Go to https://github.com and create a free account.
- Add a profile photo and fill in your name and organization.
- If you are a student, use your university email and apply for the GitHub Student Developer Pack at https://education.github.com/students. It unlocks GitHub Copilot, unlimited private repos, and additional tools at no cost.
Step 5: Install Git and GitHub CLI in WSL
Git is the version control system. gh is the GitHub command-line tool that handles authentication and repository management from your terminal.
5a. Install Git
sudo apt install git -y
5b. Configure your identity
Git needs to know who you are so your commits are properly attributed:
git config --global user.name "Your Name"
git config --global user.email "your-github-email@example.com"
Use the email address registered to your GitHub account.
5c. Install the GitHub CLI
sudo apt install gh -y
5d. Authenticate with GitHub
gh auth login
When prompted, choose:
- GitHub.com
- HTTPS
- Login with a web browser
It displays a one-time code. Copy the code, open the browser URL it shows, paste the code, and authorize the connection. You are now authenticated.
5e. Verify everything
git --version
gh --version
gh auth status
All three commands should return version numbers or a confirmed login status with no errors.
Step 6: Install Claude Code and Build Your First App
Claude Code is an agentic AI coding assistant that runs in your terminal. You give it natural language instructions and it writes, edits, and runs code across multiple files without stopping to ask for permission on each step.
6a. Install Node.js 20 via NodeSource
Node.js is required for the npm install path. The NodeSource repository provides a current, LTS-pinned build:
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
Verify the install:
node --version
npm --version
Both should print version numbers.
6b. Configure a user-level npm directory
This step avoids permission errors and means you never need sudo for global package installs. It is a one-time setup:
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
After running source ~/.bashrc, any globally installed npm package is available immediately.
6c. Install Claude Code
Try the native installer first (recommended; no Node.js dependency):
curl -fsSL https://claude.ai/install.sh | bash
If that does not work in your WSL environment, fall back to npm:
npm install -g @anthropic-ai/claude-code
Verify the install:
claude --version
6d. Build your first app
Create a project folder and launch Claude Code with the --dangerously-skip-permissions flag. This flag (also called YOLO mode) lets Claude Code execute multi-step tasks continuously without stopping for per-action confirmation. It is appropriate for personal projects and isolated learning environments:
mkdir -p ~/git/helloworld
cd ~/git/helloworld
claude --dangerously-skip-permissions
Once inside the Claude Code session, type:
Build me a simple Hello World web app with HTML, CSS, and JavaScript. Give it a clean modern look with a centered card, a heading that says 'Hello World', a subtitle with today's date, and a button that shows an alert when clicked. Save everything in this folder.
Claude Code creates the files. When it finishes, type exit to close the session.
6e. Preview your app
Open Windows Explorer and navigate to:
\\wsl$\Ubuntu\home\yourname\git\helloworld\index.html
Double-click the file to open it in your browser.
Step 7: Open Your Project in VS Code
From your WSL terminal, navigate to your git folder and open it in VS Code:
cd ~/git
code .
VS Code opens with the WSL Remote extension active. You will see WSL: Ubuntu in green in the bottom-left corner. The Explorer panel on the left shows your helloworld folder and all the files Claude Code created.
From here you can edit files directly, open the integrated terminal (which drops into WSL), run tests, commit changes, and use all of VS Code's features as though you were working natively on Linux.
Best Practices for AI-Assisted Development
Work in WSL-native paths. Always work inside your WSL home directory (~/), not in Windows paths (/mnt/c/...). Cross-filesystem I/O is significantly slower and can produce permission issues with some tools.
Organize projects under ~/git/. One folder per project keeps your workspace clean and makes git operations predictable.
Use /plan before writing code. Before asking Claude Code to implement anything non-trivial, type /plan followed by your request. Claude Code will outline its approach, list files it intends to touch, and surface design decisions before writing a single line. Reviewing the plan takes thirty seconds and prevents hours of unwanted changes. It is the single most effective habit for keeping AI-generated work aligned with your intent.
Ask Claude Code to commit, don't do it yourself. Instead of running git add . && git commit manually, tell Claude Code: "commit everything with a descriptive message and exit." It stages the right files, writes a meaningful commit message, and closes the session cleanly. This keeps your git history readable and avoids accidentally committing in-progress or unrelated changes.
Keep context small. Every message in a Claude Code session adds to the context window. A long session with many file reads and back-and-forth exchanges makes Claude Code slower and more likely to lose track of earlier decisions. Use /clear to reset the conversation without ending the session, or type exit and start fresh for each distinct task. For large tasks that span multiple work areas, use /context to check what is loaded and drop files you no longer need. Small, focused sessions consistently produce better results than marathon ones.
Know when to skip YOLO mode. --dangerously-skip-permissions is useful for learning and personal projects, but it bypasses Claude Code's per-step confirmation prompts. On shared repositories or production codebases, let Claude Code ask for confirmation on each action so you maintain oversight.
Monitor your usage. Claude Code requires a Claude Pro subscription or Anthropic API credits. If you hit a rate limit, check your billing and usage at console.anthropic.com.
What's Next?
This setup gives you a complete foundation for AI-assisted development on Windows. From here you can:
For teams looking to bring agentic AI into enterprise workflows with HITL controls, private-by-architecture deployment, and outcome-based contracts, talk to the lowtouch.ai team.
