Claude Code WSL2 Setup

My active Claude Code setup for WSL2 + Windows Terminal, built around one idea: keep Claude focused on orchestration and hand implementation churn to Codex.

The repo only tracks the pieces I actually use: Codex delegation, LangSmith tracing, LSP navigation, screenshot paste, Windows notifications, statusline, and token/context hygiene hooks.

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 long implementation loops can move to Codex without filling Claude's main conversation.

Start with codex-delegate if your main pain is context burn. Start with image-paste and claude-notify if your main pain is day-to-day Windows/WSL friction.

Delegate implementation without filling Claude's main context

Large implementation tasks are expensive twice: Claude spends tokens doing the work, then keeps every file read, edit, test run, and retry in the main conversation. That history competes with the architecture and product context Claude needs to orchestrate well.

codex-delegate sends a well-specified implementation task to Codex through an isolated Claude subagent. Codex does the read/edit/test loop; the main session gets back a short result and keeps its context for planning, steering, and review.

In the real run below, two Codex delegates handled tens of thousands of worker tokens in parallel while the main Claude session still showed 8% context and 6% five-hour usage.

Codex does the implementation; the main Claude context receives only a compact summary.

Set up Codex delegation →

Featured fixes

Start with these — they are the highest-leverage pieces in the repo:

• Codex delegate — routes large mechanical implementation to Codex through an isolated low-effort Sonnet wrapper, keeping the premium Claude orchestrator context clean.
• LSP setup — lets Claude use real Go-to-Definition / reference navigation instead of burning tokens on broad file search.
• LangSmith tracing — trace selected Claude Code projects without enabling telemetry for every local session.
• Image paste — paste a Windows screenshot into Claude Code or Codex as a usable WSL file path.
• Distinct terminal titles — label zsh tabs by the current project and active agent, such as text2sql-agent · ✳ Claude or text2sql-agent · >_ Codex.
• Notifications (Claude Code · Codex) — get a Windows notification when either agent finishes, while suppressing alerts when Windows Terminal is already focused.
• Secrets hygiene hook — blocks credential-file reads before secrets can land in the transcript.
• Bash output truncation hook — trims huge command output to head+tail so one verbose test/build log does not bloat the rest of the context.

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.

What it fixes

• Image paste — copy a screenshot on Windows and paste the file path straight into Claude Code or Codex. A systemd user service keeps wsl-screenshot-cli running, saves new screenshots under /tmp/.wsl-screenshot-cli/, and restarts the clipboard monitor if it exits.
• 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 on Claude Code Notification events when Claude finishes, asks for permission, or a background agent completes; 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.
• LangSmith tracing — send selected Claude Code project turns, tool calls, subagent runs, and compaction events to project-specific LangSmith traces.
• Secrets hygiene hook — blocks Claude from reading credential files into the transcript with Read, Grep, or content-printing shell commands.
• Bash output truncation hook — cuts huge command output (test runs, build logs, JSON dumps) down to head+tail with an omission marker, so one verbose command doesn't eat the context window for the rest of the session.
• Ruff auto-format hook — formats Python files after every Claude edit, but only in projects that declare Ruff configuration.
• 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.

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.

For a manual install, copy the relevant files from agents/, skills/, hooks/, and scripts/ into the matching ~/.claude/ directories, then read the linked setup page for the feature you want.

What's included

Claude Code core

Agent workflows

Safety and context hygiene

WSL / Windows bridge

Custom agents and skills

Copy the matching files from agents/, skills/, hooks/, and scripts/ to ~/.claude/agents/, ~/.claude/skills/, ~/.claude/hooks/, and ~/.claude/scripts/ for Claude Code.

After adding or updating a skill, run /reload-skills to make it available without restarting the session. Custom agents still require a restart.

Codex skills and the rest of my Codex setup live in the companion repo congmnguyen/codex-wsl2-setup.

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.

Pruned notes

Native Windows PowerShell notifications, WSLg voice-mode audio, and uninstalled Claude skills were removed from the main repo because they are not part of the active local setup.

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/:

  hljs language-bash

  Copy

  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.