Skip to content
CC Switch WikiUnofficial Community Wiki

'claude' is not an internal or external command, nor a runnable program - CC Switch

Quick fix

Upgrade to v3.16.2+ to fix WSL/Windows path detection, or manually configure install directory override.

Symptom

Section titled “Symptom”
Error output
'claude' 不是内部或外部命令，也不是可运行的程序
或批处理文件。
找不到批处理文件。
English translation

'claude' is not an internal or external command, nor a runnable program or batch file. Batch file not found.

Cause

Section titled “Cause”

This issue mainly occurs when using CC Switch to launch terminals on Windows. The root cause usually involves two aspects:

1. **Environment variable inheritance differences**: On Windows, the terminal process launched by CC Switch may only inherit system-level PATH variables, missing user-level PATH variables (which typically contain Node.js or Claude CLI install paths). This prevents the system from finding the `claude` command.

2. **WSL and native environment path resolution errors**: When users connect to Claude CLI in WSL via CC Switch on Windows, or use specific versions (e.g., v3.16.3), the tool's path scanning logic may fail to correctly identify binaries within WSL or virtual environment paths created by official install scripts (such as Hermes Agent). Although multi-platform CLI discovery support for WSL was introduced in v3.16.0/3.16.1, some users report path matching failures in subsequent versions, resulting in "claude not found" or command execution failure.

For macOS users, if the terminal app is already running, the `open -a` command may ignore new parameters, causing silent failures; ensure the `-na` flag is used to force a new instance.

Fix

Section titled “Fix”

  1. Upgrade CC Switch to the latest version (recommended v3.16.2 or higher) to get the latest WSL handling and path scanning fixes.

  2. If the issue persists after upgrading, use the 'Configure Directory Override' feature in CC Switch settings to manually specify the actual install directory of WSL or local Claude CLI.

    在 CC Switch UI 中找到 'App Directory Override' 或类似选项
    # 填入 WSL 路径，例如: /home/<username>/.nvm/versions/node/vXX.XX.X/bin
    # 或 Windows 本地路径: C:\Users\<User>\AppData\Roaming\npm

  3. Verify environment variables: Run `echo $PATH` (Linux/macOS) or `echo %PATH%` (Windows) in the terminal launched by CC Switch to confirm it includes the directory containing claude. If missing, add it to the system environment variables.

Affected Versions

Section titled “Affected Versions”
ToolClaude Code
Version3.16.3
PlatformsWindowsmacOSLinux

Source Issues

Section titled “Source Issues”

This page is distilled from 18 real issues

FAQ

Section titled “FAQ”
Why does it work when I open the terminal myself but error with CC Switch?
This is because the environment variables inherited by the child process launched by CC Switch may differ from those of the currently logged-in user. Especially on Windows, system and user PATH variables may be separated, preventing CC Switch from finding CLI tools installed under the user directory.
How to configure Claude in WSL on Windows?
You can use the 'Configure Directory Override' feature in CC Switch. In settings, point the App install directory to the path in WSL (e.g., `/home/user/.nvm/versions/node/v.../bin`), allowing CC Switch to call executables inside WSL from the Windows side.
Nothing happens or errors occur when clicking Open Terminal on macOS?
If the target terminal app (such as Ghostty, Alacritty) is already running, `open -a` will default to activating the existing window and ignoring new parameters. This issue has been fixed at the code level by adding the `-n` flag (force new instance); please ensure you upgrade to the latest version.
Hermes Agent shows uninstalled but available via command line?
This is caused by the path scanning logic not covering the default path `%LOCALAPPDATA%\hermes\hermes-agent\venv\Scripts` created by the official `install.ps1`. A temporary workaround is to create a symlink or wrapper script pointing to hermes.exe in this venv under `~/.local/bin/`.
Section titled “Related problems”
bash: cannot set terminal process group - cc-switchA known 3.18.0 bug when checking the local proxy environment on Linux. Downgrade below 3.18.0 and configure the proxy in the terminal by hand.5 issues mergedNot installed / not installed or not executable - CC SwitchUpgrade CC Switch to v3.20.0+ for custom npm prefix and macOS detection failures; the false "several installations" on Windows needs v3.16.5+.4 issues mergedOpening cc on Windows 11 gives a process but no window - cc-switchOn Windows 11, try Windows 7 compatibility in the exe properties. If that fails, use cc-switch-cli to bypass the Tauri 2 GUI white screen.6 issues merged

This is an unofficial community wiki with no affiliation to the cc-switch authors or the project itself. Its content is compiled from the project's public GitHub issues. This site distributes no software.