Repository navigation
Claude Code WSL2 Setup v2.0.0
A narrower, tested-on-CI WSL2 setup, plus a security fix for the notification script.
Verification: I now use Ubuntu + Ghostty (why).
Every change in this release passes the Linux checks in CI, but changes made after
2026-09-08 have not been run on a real WSL2 install yet. See the
verification status,
and please report results with the WSL2 issue form.
Security fix: reinstall claude-notify
The v1.0.0 notification script put message text inside PowerShell string literals.
PowerShell also ends single-quoted strings at ‘ ’ ‚ ‛, so a Codex reply containing
’ could break the notification or inject commands. The script now passes text
base64-encoded. If you use Windows notifications from Claude Code, Codex, or tmux,
reinstall it from the cloned repository:
git pull
install -m755 bin/claude-notify ~/bin/claude-notify
bash scripts/doctor.sh # flags an old copyBreaking changes
Removed. Git history keeps the old versions:
- All
PreToolUse/PostToolUsehooks:block-secret-reads,truncate-bash-output,
andformat-python-with-ruff. Each misfired in practice; see
pruned notes.
Remove their entries from~/.claude/settings.json. For secrets, use exact-match
permissions.denyrules instead. - Codex delegation (agent, skill, and
scripts/codex-run.sh), thecode-architect
agent, and the bundled skills. - Playwright and LangSmith tracing guides.
New
scripts/doctor.sh: a read-only report of installed scripts, settings, and WSL2
prerequisites, and it flags known conflicts. Include its output in bug reports.- Terminal titles:
zsh tab titles that tell Claude Code and Codex tabs apart. bin/tmux-notify-run: detached tmux jobs with logs, exit status,--status, and a
Windows notification when they finish.- Shared scripts now live in
bin/, with maintenance
steps for backup, verification, and removal. - CI checks: shellcheck, Markdown links, documentation snippets, and behavior tests for
the statusline, notifications, tmux helper, and doctor. - Docs site: https://congmnguyen.github.io/claude-code-wsl2-setup/
Fixes
- Screenshot paste runs as a supervised systemd user service, installed from a pinned,
checksum-verified release. - Notifications: native async hooks, no un-maximizing Windows Terminal on click, and
a 12 s exit limit. - Statusline: handles missing, non-numeric, or implausibly large values; dims unused
context cells. - Browser routing: WSL-form paths, paths with spaces, and an XDG fallback for OAuth CLIs.
tmux-notify-runfinishes the log before recording the exit status.
Full changelog: v1.0.0...v2.0.0