DEV Community

QuoLu
QuoLu

Posted on

I Used Claude Code for 2 Months Without Knowing About WSL2

#claudecode #wsl2 #windows #ai

Introduction

I subscribed to Claude MAX and have been using it for coding almost every day.

In my first article, I wrote, "I didn't even know half of the features in Claude Code." I'm talking about not knowing /init or CLAUDE.md.

A month and a half has passed since then. And the same thing happened again.

One day, during a session, I was trying to run a command, and Claude said:

"I recommend running this in WSL2."

Huh.

WSL... 2?

"It runs real Linux on Windows"

When I asked what that meant, Claude explained:

  • A mechanism where the Linux kernel runs authentically inside Windows
  • Different from virtual machines like VirtualBox or VMware
  • Allows file access between Windows and Linux
  • VS Code can open folders on the Linux side directly for development

I see. I think I'd heard the name before. I might have seen it briefly in a web article.

But since I was running Claude Code natively on Windows, I thought I didn't need it.

Then, Claude dropped another bombshell.

"Claude Code only achieves about 70% of its potential performance when running natively on Windows."

What.

Seriously? Claude Code's home is Linux

The more I asked, the more I realized that Claude Code is built with Linux/macOS in mind.

  • The tools running inside are almost all based on POSIX/bash
  • Hooks and MCP server-related features run most reliably in a Linux environment
  • Official documentation and samples are mostly for bash
  • Running natively on Windows involves an abstraction layer to bridge command differences, which creates friction

In other words, I've been forcing a tool designed for Linux to work on Windows for two months.

It wasn't that it didn't work. It worked. But it probably wasn't running at full speed.

Wait, that explains so much

Hearing this, everything suddenly clicked.

I've been constantly getting stuck with Claude Code:

  • The official sample procedures were in bash, and I had to mentally convert them to PowerShell every time
  • npm package installations would fail only on Windows
  • Hooks I tried to install wouldn't run, with errors like "local variable expansion is invalid"
  • MCP server configuration examples assumed ~/.config/..., and the path structure was completely different to begin with
  • I would restart VS Code repeatedly because the extensions wouldn't respond after installation

Every time, I just resigned myself to, "Well, it's Windows, so it can't be helped..."

I spent my time searching for 'Windows-specific solutions,' clicking through endless blue links on StackOverflow, and burning hours just to get things running.

Was all of this just because I wasn't using WSL2?

Are you kidding me?!!

Seriously, are you kidding me?

That plugin I gave up on that night, that hook I struggled to get working—if I had been running them on Linux from the start, would it have been instant?

Give me back my weekends.

Claude, you again...

I'm getting a strong sense of déjà vu here.

It was the same when I didn't know about /init.

It was the same when I didn't know about CLAUDE.md.

It was the same when I wasn't using Plan mode.

And now, WSL2.

The problem where Claude doesn't tell you the most important things voluntarily—I think this is a trap common across the industry.

New users don't read the official documentation from top to bottom, and it doesn't display a message saying, "Your environment isn't performing at its best" upon startup. Since it works well enough, you can end up running it like that for months.

Other Windows-native Claude Code users out there, you're probably running it hard right this second.

Running it, but only at 70% of Claude's true potential.

Tell me sooner, Claude!!

I moved

So, I moved to WSL2. The process was surprisingly easy.

Open PowerShell as administrator and run one command:

wsl --install
Enter fullscreen mode Exit fullscreen mode

That downloads the default Ubuntu, and after a restart and creating a user, that's it. After that, install the WSL extension in VS Code, select "Connect to WSL" from the green button at the bottom left, and VS Code connects seamlessly to the Linux side.

Reinstalling Claude Code was straightforward in the Linux terminal. In fact, I could use the steps from the official documentation as-is. No need to read Windows-specific caveats. This is powerful.

There was only one trap: You shouldn't access projects located in Windows folders directly from the Linux side. Going through /mnt/c/... makes file access extremely slow, which ruins the benefits of WSL2. The correct way is to git clone your projects on the Linux side (somewhere like ~/projects/).

The result of the move

It feels faster.

  • Terminal operation response is snappy
  • Commands like npm install and hugo build are visibly faster
  • I can follow official tutorials without issues, so I get stuck less often
  • Hooks and small scripts written in bash work as-is without conversion

It's hard to prove with numbers, and I didn't run benchmarks to calculate that "missing 30%" difference.

However, it is clear that I get stuck less often. This is a matter of efficiency, and in my experience, the several "why isn't this working" moments I had each day have disappeared. That alone makes it worth it.

Summary

If you're going to use Claude Code extensively, I think you should consider WSL2 a prerequisite.

There are things you can manage with native Windows, but if you want to unleash its true behavior, it's best to place it on the Linux side.

Along with /init and CLAUDE.md, WSL2 is now the first thing I want to tell beginners.

The official documentation is in English, and it doesn't tell you this at startup, so it's natural that people don't realize it.

That's why I'm writing this. To save at least one person from wasting two months in the same trap I fell into.

Top comments (0)