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.

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.

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 →

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.
• 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.

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

• 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 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.
• 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.

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.

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.

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.

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.

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

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