Fix "Could not locate the Claude CLI on PATH" — VS Code Extension

Getting "Failed to run Claude Code: Error: Could not locate the Claude CLI on PATH" in VS Code while claude runs perfectly in your terminal? This is the IDE extension's own discovery logic failing — the CLI is usually installed and healthy.

The Error

Failed to run Claude Code: Error: Could not locate the Claude CLI on PATH

Other IDE integrations word the same failure differently:

❌ Error: Claude CLI not found. Please install Claude Code CLI.

Both mean the same thing: the editor looked for the claude executable and did not find it. Neither means your installation is broken, and neither is a permission problem — for zsh: permission denied: claude see Claude Code permission errors instead.

Why This Happens

In rough order of frequency:

1. The editor's PATH differs from your shell's PATH. GUI applications launched from Finder, the Dock, or the Start menu do not inherit the environment your interactive shell builds. ~/.local/bin is added by your ~/.zshrc or ~/.bashrc, which a GUI launch never reads.
2. A known extension regression. A detection bug was reported in the VS Code extension starting at v2.1.214, with v2.1.212 and earlier working correctly. It was reproduced with the CLI binary already at a newer version, confirming the fault is in the extension's detection logic rather than the CLI. Windows usernames containing non-ASCII characters (for example C:\Users\山田太郎\) were implicated.
3. Only the extension is installed. The VS Code extension bundles a private copy of the CLI for its chat panel and does not put claude on your PATH. If you never ran a standalone install, ~/.local/bin/claude genuinely does not exist.
4. The CLI is installed somewhere the extension does not check — a Homebrew, WinGet or npm global location rather than the standard native path.
5. The editor was open across the install. VS Code caches the environment it started with.

Fix 1: Check PATH From Inside the Editor

This is the diagnostic that settles it. Open the editor's integrated terminal — not a separate terminal app — and run:

which claude          # macOS / Linux
echo $PATH | tr ':' '\n' | grep -F "$HOME/.local/bin"

where.exe claude      # Windows
$env:PATH -split ';' | Select-String '\.local\\bin'

Interpret the result:

• Prints a path → the CLI is discoverable in the editor's environment. Your problem is the extension itself; go to Fix 4.
• Prints nothing → the editor's PATH is missing the install directory. Go to Fix 2.

Comparing this against the same commands in a standalone terminal is what reveals the environment mismatch that makes this error so confusing.

Fix 2: Put the Install Directory on PATH

The native installer places the binary at ~/.local/bin/claude on macOS and Linux — a symlink into ~/.local/share/claude/versions/ — and at %USERPROFILE%\.local\bin\claude.exe on Windows.

# Zsh (default on macOS)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Windows — adds to your User PATH permanently
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

Then quit the editor completely and reopen it. Reloading the window is not enough on macOS or Windows — the process must restart to pick up a changed environment. On macOS, launching VS Code with the code command from a terminal inherits your full shell environment and is a quick way to confirm the diagnosis before you commit to the PATH edit.

Fix 3: Confirm the CLI Is Actually Installed

If which claude prints nothing anywhere, including a normal terminal, you do not have a standalone install. The extension's bundled copy does not count.

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

Full per-platform options, including Homebrew and WinGet, are in our guide to installing the Claude Code CLI.

Verify before returning to the editor:

claude --version

A working installation prints a version number such as 2.1.211 (Claude Code).

Fix 4: Work Around the Extension Regression

If the CLI resolves inside the editor's integrated terminal but the extension still reports it missing, you are looking at the extension's detection bug rather than your configuration. Two options:

Pin an older extension build. In the Extensions view, click the gear icon on Claude Code for VS Code, choose Install Specific Version, and select a build from before the regression boundary. Then disable auto-update for that extension so it does not immediately re-upgrade.

Or update to the newest build. If a fix has shipped since the regression was reported, taking the latest version is the cleaner path. Check the extension's changelog before deciding which direction to move.

Either way, restart the editor fully afterwards.

Verify the Fix

Run the CLI's own diagnostics from the editor's integrated terminal, so you are testing the environment the extension actually sees:

claude --version
claude doctor

claude doctor prints read-only installation and settings diagnostics without starting a session, including install health and any warnings with suggested fixes.

Then start a session from the extension. Success is the extension launching a session rather than showing the error — the terminal working was never in doubt.

If the extension still fails while the integrated terminal succeeds, capture both outputs and the extension version before filing a report; that combination is exactly what distinguishes an extension bug from a local misconfiguration.

Prevention

• After installing or moving the CLI, fully quit and reopen your editor rather than reloading the window.
• Keep one installation method. A Homebrew install plus an npm global install plus the native installer is how "I updated but it still points at the old one" starts. Check with which -a claude.
• If you rely on the extension for daily work, consider disabling its auto-update and upgrading deliberately, so a detection regression cannot arrive unannounced mid-sprint.
• Remember the extension does not provide a PATH-accessible claude; always keep a standalone install alongside it.

Summary

1. Run which claude in the editor's integrated terminal — this separates a PATH problem from an extension bug
2. Path prints nothing → add ~/.local/bin (or %USERPROFILE%\.local\bin) to PATH and fully restart the editor
3. Nothing anywhere → you never did a standalone install; the extension's bundled copy is not on PATH
4. Path prints fine but the extension still fails → suspect the v2.1.214+ detection regression and pin or update the extension
5. Confirm with claude doctor from inside the editor, not a separate terminal