Claude Code Wsl2 Setup

Claude Code on WSL (WSL2): Setup and Fixes

Fixes for running Claude Code on WSL / WSL2 with Windows Terminal: paste Windows
screenshots into Claude Code, get Windows notifications when it finishes or needs
permission, make Shift+Enter insert a newline, open login links in your Windows
browser, use LSP navigation, and add a statusline for context and usage.
Maintenance status: I now use Ubuntu + Ghostty and no longer test this setup
daily on WSL2 (why I moved). The guides stay focused on WSL2.
Bug reports and fixes are welcome: use the WSL2 issue form
and include the output of bash scripts/doctor.sh. The
verification status lists changes that
still need a WSL2 run.

Install Claude Code on WSL first

This repository starts after installation. To install Claude Code inside WSL, follow
the official Install in WSL
instructions, then come back for the fixes below.

Who this is for

Use this if you run Claude Code from WSL2 and want the Windows side to stop feeling
bolted on: screenshots paste as WSL paths, notifications land in Windows, browser
links open in your normal browser, and the statusline shows context and usage.

Where to start, depending on what hurts most:

- Context burn → lsp-setup.
- Windows/WSL friction → image-paste and claude-notify.
- No visibility into context and usage → statusline.

Preview

  claude-code-wsl2-setup | main | [··········] 6% | 5h:10% | W:95%

  Balloon tip fires on Claude Code Notification events, skipped when Windows Terminal is focused

  Codex's top-level notify command shows the completed turn's last reply

  Shell-managed titles keep Claude Code and Codex tabs distinguishable.

Setup

These instructions target WSL2 + Windows Terminal. Start with the guide for the
feature you need; optional integrations are separate choices.

Then…