convez.ai
PluginDevOps & InfraestruturaIntermediário
congmnguyen

Claude Code WSL2 Setup

congmnguyen/claude-code-wsl2-setup

Correções e LSP para Claude Code rodar fluidamente em WSL2

Ver no GitHub
BomPluginScore · de 0 a 100

Conjunto 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-setup

1 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

Estrelas
56
Forks
4
Acompanhando
0
Saúde
42%
Último commit
há 16 horas
Versão
v2.0.0
Issues abertas
0
Contribuidores
1

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: Claude git 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 /voice works, 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

FileFix
lsp-setup.mdLSP — official plugins + language servers for TypeScript, Python, Go, Rust
image-paste.mdScreenshot paste — wsl-screenshot-cli daemon + optional Alt+V keybinding
shift-enter.mdShift+Enter newline in VSCode terminal and Windows Terminal
claude-notify.mdWindows balloon tip — WSL2 variant for Claude Code Stop / PermissionRequest hooks and Codex notify
claude-notify-powershell.md + claude-hook-toast.ps1Windows toast — native PowerShell variant
statusline.mdStatus line — project dir, git branch, context bar, 5h / 7d usage
settings.mdDisable git attribution, skip trust dialog
browser.mdOpen links in your Windows browser via BROWSER env var
mcp-setup.mdDeepWiki, Playwright, and Figma Desktop MCP servers
playwright-cli.mdPlaywright CLI — token-efficient browser automation; preferred over Playwright MCP for coding agents
voice.mdVoice mode — ALSA → PulseAudio → WSLg bridge, ~/.asoundrc + PULSE_SERVER
capslock-esc.mdCapsLock → Escape — registry-level remap via SharpKeys (Windows-side only)

Custom agents and skills

PathContents
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.md into ~/.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.

Ver o original no GitHub

Bom para

Relacionados