{"id":50243066,"url":"https://github.com/congmnguyen/claude-code-wsl2-setup","last_synced_at":"2026-06-12T14:00:36.487Z","repository":{"id":339355860,"uuid":"1161527482","full_name":"congmnguyen/claude-code-wsl2-setup","owner":"congmnguyen","description":"Fixes for Claude Code papercuts on WSL2 + Windows Terminal: image paste, notifications, statusline, LSP, voice mode, and more.","archived":false,"fork":false,"pushed_at":"2026-06-11T03:24:31.000Z","size":630,"stargazers_count":21,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T05:12:22.665Z","etag":null,"topics":["anthropic","claude","claude-code","cli","developer-tools","dotfiles","lsp","windows-terminal","wsl","wsl2"],"latest_commit_sha":null,"homepage":"https://github.com/congmnguyen/claude-code-wsl2-setup","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/congmnguyen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-19T07:59:36.000Z","updated_at":"2026-06-11T03:24:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/congmnguyen/claude-code-wsl2-setup","commit_stats":null,"previous_names":["congmnguyen/claude-code-wsl2-setup"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/congmnguyen/claude-code-wsl2-setup","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/congmnguyen%2Fclaude-code-wsl2-setup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/congmnguyen%2Fclaude-code-wsl2-setup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/congmnguyen%2Fclaude-code-wsl2-setup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/congmnguyen%2Fclaude-code-wsl2-setup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/congmnguyen","download_url":"https://codeload.github.com/congmnguyen/claude-code-wsl2-setup/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/congmnguyen%2Fclaude-code-wsl2-setup/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34247461,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","claude","claude-code","cli","developer-tools","dotfiles","lsp","windows-terminal","wsl","wsl2"],"created_at":"2026-05-26T22:00:27.795Z","updated_at":"2026-06-12T14:00:36.481Z","avatar_url":"https://github.com/congmnguyen.png","language":"PowerShell","funding_links":[],"categories":["WSL Tools"],"sub_categories":["10. GUI Apps"],"readme":"# Claude Code WSL2 Setup\n\nFixes for the most annoying Claude Code papercuts on WSL2 + Windows Terminal.\n\n## Turn on LSP so Claude reads code like an IDE, not grep\n\nOut of the box Claude Code falls back to text search when it needs to find a function or\ntrace a reference. That's why \"find the auth handler\" sometimes drifts into the wrong file.\n\nLSP plugins ship with Claude Code since v2.0.74 — they wire Claude into the same language\nservers VSCode uses for Go-to-Definition. Once the four official plugins are installed and\nthe binaries are on your PATH:\n\n- `\"add a stripe webhook to my payments page\"` jumps straight to the existing payment module\n- `\"fix the auth bug on my dashboard\"` follows the actual call hierarchy instead of guessing\n- After every edit Claude picks up type errors immediately instead of finding them 10 prompts later\n\nIt also saves tokens, because Claude stops scrolling through files that don't match.\n\n2-minute setup. TypeScript, Python, Go, Rust. **[→ LSP setup guide](lsp-setup.md)**\n\n---\n\n## Preview\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/statusline.png\" alt=\"Custom statusline showing project, context bar, 5h and weekly usage\" width=\"640\"\u003e\u003cbr\u003e\n  \u003cem\u003evideo-site | main | [████░░░░░░] 42% | 5h:28% | W:4%\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/notification.png\" alt=\"Windows balloon tip notification — Claude Code Done!\" width=\"420\"\u003e\u003cbr\u003e\n  \u003cem\u003eBalloon tip fires on \u003ccode\u003eStop\u003c/code\u003e and \u003ccode\u003ePermissionRequest\u003c/code\u003e, skipped when Windows Terminal is focused\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/birchline-html.png\" alt=\"Birchline HTML artifact preview — paper recap with tabs and before/after code panels\" width=\"720\"\u003e\u003cbr\u003e\n  \u003cem\u003eBirchline HTML skill — single-file document-style artifacts with tabs, cards, and before/after panels\u003c/em\u003e\n\u003c/p\u003e\n\n## What it fixes\n\n- **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](https://github.com/Nailuu/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.\n- **Shift+Enter newline** — insert a newline without submitting, in both the VSCode integrated terminal and Windows Terminal.\n- **CapsLock → Escape** — remap CapsLock to Escape system-wide via SharpKeys (registry-level, works in WSL2, Vim, games, and elevated processes).\n- **\"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.\n- **Status line** — project directory, git branch, context-window fill bar, and 5-hour / 7-day usage, color-coded by severity.\n- **Settings tweaks** — disable the `Co-authored-by: Claude` git attribution and pre-accept the project trust dialog.\n- **Windows browser** — open links and OAuth flows in your existing Windows browser instead of Chromium inside WSL2.\n- **Voice mode** — fix ALSA errors so `/voice` works, routing audio through WSLg's PulseAudio server.\n\n## Setup\n\n```bash\ngit clone https://github.com/congmnguyen/claude-code-wsl2-setup.git\ncd claude-code-wsl2-setup\nclaude\n```\n\nThen prompt:\n\n\u003e Set this up\n\nClaude will read the docs and configure everything.\n\n## What's included\n\n| File | Fix |\n|------|-----|\n| [`lsp-setup.md`](lsp-setup.md) | **LSP** — official plugins + language servers for TypeScript, Python, Go, Rust |\n| [`image-paste.md`](image-paste.md) | Screenshot paste — wsl-screenshot-cli daemon + optional Alt+V keybinding |\n| [`shift-enter.md`](shift-enter.md) | Shift+Enter newline in VSCode terminal and Windows Terminal |\n| [`claude-notify.md`](claude-notify.md) | Windows balloon tip — WSL2 variant for Claude Code `Stop` / `PermissionRequest` hooks and Codex `notify` |\n| [`claude-notify-powershell.md`](claude-notify-powershell.md) + [`claude-hook-toast.ps1`](claude-hook-toast.ps1) | Windows toast — native PowerShell variant |\n| [`statusline.md`](statusline.md) | Status line — project dir, git branch, context bar, 5h / 7d usage |\n| [`settings.md`](settings.md) | Disable git attribution, skip trust dialog |\n| [`browser.md`](browser.md) | Open links in your Windows browser via `BROWSER` env var |\n| [`mcp-setup.md`](mcp-setup.md) | DeepWiki, Playwright, and Figma Desktop MCP servers |\n| [`playwright-cli.md`](playwright-cli.md) | Playwright **CLI** — token-efficient browser automation; preferred over Playwright MCP for coding agents |\n| [`voice.md`](voice.md) | Voice mode — ALSA → PulseAudio → WSLg bridge, `~/.asoundrc` + `PULSE_SERVER` |\n| [`capslock-esc.md`](capslock-esc.md) | CapsLock → Escape — registry-level remap via SharpKeys (Windows-side only) |\n\n## Custom agents and skills\n\n| Path | Contents |\n|------|----------|\n| [`agents/`](agents/) | `code-architect`, `code-simplifier` |\n| [`skills/`](skills/) | `birchline-html`, `commit-push-pr`, `dedupe`, `deep-teach`, `frontend-design`, `handoff`, `oncall-triage`, `spec` |\n| [`codex-skills/`](codex-skills/) | Codex-native versions: `code-review`, `commit-push-pr`, `dedupe`, `frontend-design`, `handoff`, `oncall-triage`, `spec` |\n\nCopy [`agents/`](agents/) and [`skills/`](skills/) to `~/.claude/agents/` and `~/.claude/skills/` for Claude Code. Copy [`codex-skills/`](codex-skills/) to `~/.codex/skills/` for Codex.\n\n## Recommended third-party skills\n\nSkills not authored here but worth installing alongside the setup:\n\n- **[liteparse](https://github.com/run-llama/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](https://simonw.github.io/liteparse/). Then install the npm package globally and copy the upstream `SKILL.md` into `~/.claude/skills/liteparse/`:\n\n  ```bash\n  npm i -g @llamaindex/liteparse\n  sudo apt-get install -y libreoffice   # required for DOCX/PPTX/XLSX\n  ```\n\n## License\n\n[MIT](LICENSE) — feel free to copy, fork, or adapt for your own setup.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcongmnguyen%2Fclaude-code-wsl2-setup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcongmnguyen%2Fclaude-code-wsl2-setup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcongmnguyen%2Fclaude-code-wsl2-setup/lists"}