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; please include your environment and reproduction steps.

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

Agent workflows

File	Fix
mcp-setup.md	Optional project-specific Figma Desktop MCP

WSL / Windows bridge

File	Fix
image-paste.md	Copy a screenshot on Windows, paste the file path straight into Claude Code or Codex. A systemd user service keeps wsl-screenshot-cli running, saves shots under /tmp/.wsl-screenshot-cli/, and restarts the monitor if it exits. Optional Alt+V keybinding
terminal-title.md	Distinct zsh tab titles for the current project and active agent, such as text2sql-agent · ✳ Claude or text2sql-agent · >_ Codex
claude-notify.md	Windows balloon tip on Claude Code Notification events — Claude finished, needs permission, or a background agent completed — suppressed when Windows Terminal is already focused
codex-notify.md	Reuse the same balloon script through Codex's top-level notify command
bin/tmux-notify-run	Detached tmux jobs with logs, exit status, and Windows completion notification
shift-enter.md	Shift+Enter inserts a newline instead of submitting, in both the VSCode integrated terminal and Windows Terminal
browser.md	Open links and OAuth flows in your Windows browser via BROWSER, plus an XDG fallback for OAuth CLIs
capslock-esc.md	CapsLock → Escape via a SharpKeys registry remap — works in WSL2, Vim, games, and elevated processes

Optional extras

Agents, project skills, and third-party tools are available separately. They are not required for the WSL2 setup. Older delegation components remain in archive.

Troubleshooting

If a hook, plugin, or other customization breaks Claude Code, start a clean diagnostic session with claude --safe-mode. Use /doctor, /hooks, and /mcp to inspect the installation and loaded integrations.

Maintenance and checks

See maintenance for backups, verification, removal, and the scope of automated checks. Windows behavior still needs testing on WSL2.

Pruned notes

I removed hooks that truncated useful output, misclassified file reads, or changed code unexpectedly. Read the failure notes for the details.

License

MIT — feel free to copy, fork, or adapt for your own setup.