windoctor

Tiếng Việt: README.vi.md

Claude Code or Codex CLI not working on Windows 11? Install went fine, claude or codex is "not recognized", hooks die silently, Vietnamese/CJK input breaks?

windoctor answers that in ten seconds. One command, zero dependencies, nothing installed, nothing changed. It checks the things that actually break coding agents on Windows and prints the exact fix for each.

npx windoctor

Not on npm yet in your region, or want the bleeding edge? Same thing straight from GitHub:

npx github:ShenJun93/windoctor

windoctor 0.1.0 — Claude Code / Codex CLI on Windows

✔ PASS Windows detected
✔ PASS Node.js version
✖ FAIL npm global bin is NOT on PATH
       C:\Users\you\AppData\Roaming\npm — this is the #1 cause of 'claude' is not recognized right after npm i -g.
       fix: Add it to your user PATH, then open a new terminal: ...
! WARN `python3` is not on PATH (only `python`)
       Claude Code hooks and many plugins written for macOS/Linux call `python3`. On this machine that fails with `python3: command not found`.
       fix: copy "C:\Python313\python.exe" "C:\Python313\python3.exe"
✔ PASS Git Bash found
! WARN Windows Terminal installed but not in use
       ref: anthropics/claude-code#826, #14828
...
1 FAIL · 2 WARN · 9 PASS · 3 INFO

Symptoms it explains (exact error text, for searchers)

• 'claude' is not recognized as an internal or external command, operable program or batch file. (cmd)
• claude : The term 'claude' is not recognized as the name of a cmdlet, function, script file, or operable program. (PowerShell)
• 'codex' is not recognized as an internal or external command / codex cli not working on windows
• Claude Code not working in PowerShell, Windows Terminal, or the VS Code terminal right after install
• python3: command not found from a Claude Code hook (Stop, PreToolUse, PostToolUse, SessionStart)
• claude.ps1 cannot be loaded because running scripts is disabled on this system
• Claude Code requires Git for Windows / Git Bash not found
• UnicodeEncodeError: 'charmap' codec can't encode character in a hook
• ENAMETOOLONG / Filename too long during npm install -g @anthropic-ai/claude-code
• Vietnamese, Japanese, Chinese or Korean characters dropped or duplicated while typing in the terminal
• Codex in WSL storing config or worktrees on the Windows side (CODEX_HOME)

Use it from inside Claude Code or Codex

The repo doubles as an agent skill. Install it once and the agent runs the diagnosis for you when you describe a Windows failure:

npx skills add ShenJun93/windoctor      # any agent supported by skills.sh
claude plugin install ShenJun93/windoctor   # Claude Code plugin form

What it checks

Check	Symptom it explains
npm global bin on PATH	'claude' is not recognized, 'codex' is not recognized right after install
Node.js / npm version	install failures, ERR_REQUIRE_ESM
claude / codex on PATH, duplicates	wrong version runs, hanging --version
Git for Windows + Git Bash	Claude Code refuses to start; hooks fail
bash shadowed by WSL's System32\bash.exe	hooks silently run inside WSL
Microsoft Store python/python3 stubs	python3: command not found, Store window opens
python3 alias missing	Stop/PreToolUse hooks written for macOS fail
PowerShell execution policy	claude.ps1 cannot be loaded because running scripts is disabled
Console code page / PYTHONUTF8	Vietnamese, CJK, emoji become ?; UnicodeEncodeError in hooks
Long paths	ENAMETOOLONG, Filename too long in node_modules and worktrees
Windows Terminal vs conhost	flicker, scroll-to-top, IME duplicate candidates
WSL + CODEX_HOME mismatch	Codex in WSL writes config/worktrees to the Windows side
IME keyboard layouts	dropped characters while typing Vietnamese/Japanese/Chinese/Korean
~/.claude/settings.json	broken JSON silently ignored; hooks that call a missing python3

Exit code: 0 all good, 1 warnings, 2 failures. --json for machine-readable output.

Relationship to claude doctor

claude doctor is Anthropic's built-in check and you should run it too. windoctor covers what it cannot see when claude itself is not on PATH or is the wrong copy, plus the Windows-only failures around Git Bash, Python stubs, hooks, execution policy, encoding and IME, and it also covers Codex CLI.

Privacy

No telemetry, no network calls, nothing written to disk. The only numbers anyone sees are npm download counts and GitHub traffic.

What it does not do

It never modifies your system. Every fix is printed for you to run. windoctor --fix is not a thing yet; tell me in an issue which fixes you want automated.

Why this exists

As of September 2026 there are 900 open issues with "windows" in the title on anthropics/claude-code and 2,651 on openai/codex. Most first-day failures are the same six things. This tool was written by a Windows + Vietnamese-IME user who hit every one of them.

License

MIT