Skip to content

Claude Code WSL2 Setup v2.0.0

Latest

Choose a tag to compare

@congmnguyen congmnguyen released this 29 Oct 09:04
· 1 commit to main since this release
99ec216

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 copy

Breaking changes

Removed. Git history keeps the old versions:

  • All PreToolUse / PostToolUse hooks: block-secret-reads, truncate-bash-output,
    and format-python-with-ruff. Each misfired in practice; see
    pruned notes.
    Remove their entries from ~/.claude/settings.json. For secrets, use exact-match
    permissions.deny rules instead.
  • Codex delegation (agent, skill, and scripts/codex-run.sh), the code-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-run finishes the log before recording the exit status.

Full changelog: v1.0.0...v2.0.0