Claude Code WSL2 Setup

The Claude Code setup I previously used with WSL2 + Windows Terminal: screenshot paste, Windows notifications, LSP navigation, and a custom statusline.

Maintenance status: I now use Ubuntu + Ghostty and no longer test this setup daily on WSL2. These guides remain available for WSL2 users. 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.

Read why I moved from WSL2 to Ubuntu + Ghostty for the context behind the change. This repository continues to focus on WSL2.

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 what Claude did → statusline, plus optional langsmith-tracing when you want full turn-level traces.

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 agents, skills, and integrations are separate choices.

git clone https://github.com/congmnguyen/claude-code-wsl2-setup.git
cd claude-code-wsl2-setup
claude

Then prompt:

Help me set up this repository's WSL2 features. Check my environment, explain the changes, and preserve my existing settings. Leave optional components alone.

Claude can read the docs and help apply the configuration. Some steps require changes on the Windows side; see the individual guides.

For a manual install, follow the linked setup page for the feature you want. The agents/ and skills/ directories contain optional extras, not an installer for the core setup.

What's included

Claude Code core

File	Fix
lsp-setup.md	Official LSP plugins + language servers for TypeScript, Python, Go, and Rust, so Claude uses real Go-to-Definition / find-references instead of burning tokens on broad file search
statusline.md	Project dir, git branch, context-window fill bar, and 5-hour / 7-day usage, color-coded by severity
langsmith-tracing.md	Optional. Project-level LangSmith traces for turns, tool calls, subagent runs, and compaction events — without enabling telemetry for every local session
settings.md	Disabling the Co-authored-by: Claude git attribution and session links

WSL / Windows bridge