Claude Code WSL2 Setup
congmnguyen/claude-code-wsl2-setup
Correções e LSP para Claude Code rodar fluidamente em WSL2
Ver no GitHubConjunto de correções e melhorias para Claude Code rodando em WSL2 + Windows Terminal, incluindo suporte a LSP (Language Server Protocol), notificações nativas do Windows, cola de imagens e voice mode. Cobre tanto integrações WSL2-específicas quanto configurações genéricas de Claude Code que funcionam em Linux e macOS.
Instalação
npx convez-ai congmnguyen/claude-code-wsl2-setup1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Desenvolvedores usando Claude Code em WSL2 + Windows Terminal
- Ativar LSP para indexação de código como uma IDE (TypeScript, Python, Go, Rust)
- Integrar notificações nativas do Windows, cola de screenshots e remap de CapsLock
Veredito

Solução prática e focada para um problema real: fazer Claude Code trabalhar bem dentro do ecossistema WSL2/Windows. As guias de LSP e configuração economizam tokens ao melhorar a indexação de código.
README
A tradução para o português deste README ainda está na fila.
Claude Code WSL2 Setup
Fixes for the most annoying Claude Code papercuts on WSL2 + Windows Terminal.
Most of these (image paste, notifications, CapsLock→Esc, voice) bridge WSL2 to the Windows host and are WSL-specific. But the LSP, statusline, MCP, and Playwright CLI guides are plain Claude Code config — they work on any Linux or macOS too.
Turn on LSP so Claude reads code like an IDE, not grep
Out of the box Claude Code falls back to text search when it needs to find a function or trace a reference. That's why "find the auth handler" sometimes drifts into the wrong file.
LSP plugins ship with Claude Code since v2.0.74 — they wire Claude into the same language servers VSCode uses for Go-to-Definition. Once the four official plugins are installed and the binaries are on your PATH:
"add a stripe webhook to my payments page"jumps straight to the existing payment module"fix the auth bug on my dashboard"follows the actual call hierarchy instead of guessing- After every edit Claude picks up type errors immediately instead of finding them 10 prompts later
It also saves tokens, because Claude stops scrolling through files that don't match.
2-minute setup. TypeScript, Python, Go, Rust. → LSP setup guide
Preview
What it fixes
- Image paste — copy a screenshot on Windows and paste the file path straight into Claude Code or Codex. A small Go daemon (wsl-screenshot-cli) polls the Windows clipboard, saves new screenshots under
/tmp/.wsl-screenshot-cli/, and rewrites the clipboard so paste returns the WSL path. - Shift+Enter newline — insert a newline without submitting, in both the VSCode integrated terminal and Windows Terminal.
- CapsLock → Escape — remap CapsLock to Escape system-wide via SharpKeys (registry-level, works in WSL2, Vim, games, and elevated processes).
- "Needs your input" Windows notification — fires when Claude finishes a task or asks for permission, and is suppressed automatically when Windows Terminal is already focused. WSL2 variant uses a balloon tip; the native PowerShell variant uses a modern Windows toast.
- Status line — project directory, git branch, context-window fill bar, and 5-hour / 7-day usage, color-coded by severity.
- Settings tweaks — disable the
Co-authored-by: Claudegit attribution and pre-accept the project trust dialog. - Windows browser — open links and OAuth flows in your existing Windows browser instead of Chromium inside WSL2.
- Voice mode — fix ALSA errors so
/voiceworks, routing audio through WSLg's PulseAudio server.
Setup
git clone https://github.com/congmnguyen/claude-code-wsl2-setup.git
cd claude-code-wsl2-setup
claude
Then prompt:
Set this up
Claude will read the docs and configure everything.
What's included
| File | Fix |
|---|---|
lsp-setup.md | LSP — official plugins + language servers for TypeScript, Python, Go, Rust |
image-paste.md | Screenshot paste — wsl-screenshot-cli daemon + optional Alt+V keybinding |
shift-enter.md | Shift+Enter newline in VSCode terminal and Windows Terminal |
claude-notify.md | Windows balloon tip — WSL2 variant for Claude Code Stop / PermissionRequest hooks and Codex notify |
claude-notify-powershell.md + claude-hook-toast.ps1 | Windows toast — native PowerShell variant |
statusline.md | Status line — project dir, git branch, context bar, 5h / 7d usage |
settings.md | Disable git attribution, skip trust dialog |
browser.md | Open links in your Windows browser via BROWSER env var |
mcp-setup.md | DeepWiki, Playwright, and Figma Desktop MCP servers |
playwright-cli.md | Playwright CLI — token-efficient browser automation; preferred over Playwright MCP for coding agents |
voice.md | Voice mode — ALSA → PulseAudio → WSLg bridge, ~/.asoundrc + PULSE_SERVER |
capslock-esc.md | CapsLock → Escape — registry-level remap via SharpKeys (Windows-side only) |
Custom agents and skills
| Path | Contents |
|---|---|
agents/ | code-architect, code-simplifier |
skills/ | birchline-html, commit-push-pr, dedupe, deep-teach, frontend-design, handoff, oncall-triage, spec |
codex-skills/ | Codex-native versions: code-review, commit-push-pr, dedupe, frontend-design, handoff, oncall-triage, spec |
Copy agents/ and skills/ to ~/.claude/agents/ and ~/.claude/skills/ for Claude Code. Copy codex-skills/ to ~/.codex/skills/ for Codex.
Recommended third-party skills
Skills not authored here but worth installing alongside the setup:
-
liteparse (LlamaIndex, MIT) — parse PDF, DOCX, PPTX, XLSX, and images locally with no cloud calls. Useful for feeding unstructured documents into Claude or Codex without uploading them. Try it in the browser first: simonw.github.io/liteparse. Then install the npm package globally and copy the upstream
SKILL.mdinto~/.claude/skills/liteparse/:npm i -g @llamaindex/liteparse sudo apt-get install -y libreoffice # required for DOCX/PPTX/XLSX
License
MIT — feel free to copy, fork, or adapt for your own setup.