fix: Update outdated Claude Code CLI install instructions#1635
Conversation
Claude Code now distributes as a native binary rather than an npm package. Update warning/error messages and documentation to reference the official install page instead of `npm install -g @anthropic-ai/claude-code`. Closes eyaltoledano#1634
🦋 Changeset detectedLatest commit: f6eb5ae The changes in this PR will be included in the next version bump. Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
No actionable comments were generated in the recent review. 🎉 📝 WalkthroughWalkthroughUpdated Claude Code CLI detection and messaging: added filesystem/location-based binary discovery and validation, replaced npm-based install guidance with curl/install script and docs links in docs and error messages, and adjusted an ENOENT runtime error message accordingly. Changes
Sequence Diagram(s)(omitted) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (5)
docs/examples/claude-code-usage.md (1)
62-65: Consider adding Windows install instructions.The native binary install method
curl -fsSL https://claude.ai/install.sh | bashis for Linux/macOS, while Windows users needirm https://claude.ai/install.ps1 | iex. The current text doesn't note this platform split, which could leave Windows users without clear guidance.📝 Suggested update
-1. Claude Code CLI must be installed and authenticated on your system. Install from the [official docs](https://docs.anthropic.com/en/docs/claude-code/overview) or run: +1. Claude Code CLI must be installed and authenticated on your system. Install from the [official docs](https://docs.anthropic.com/en/docs/claude-code/overview) or run the appropriate command for your platform: + + **macOS/Linux:** ```bash curl -fsSL https://claude.ai/install.sh | bash ``` + + **Windows (PowerShell):** + ```powershell + irm https://claude.ai/install.ps1 | iex + ```🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/examples/claude-code-usage.md` around lines 62 - 65, The install instructions currently only show the POSIX installer command "curl -fsSL https://claude.ai/install.sh | bash"; add a Windows (PowerShell) alternative by appending a short labeled section (e.g., "**Windows (PowerShell):**") and include the PowerShell installer command "irm https://claude.ai/install.ps1 | iex", ensuring the platform split is clear to Windows users and placed next to the existing bash example..changeset/help-sync-test-enhancements.md (1)
5-5: Changeset summary should use imperative moodLine 5 uses past tense "Enhanced" — per the project's changeset convention, the summary line should be in imperative mood (e.g., "Enhance help documentation sync test to verify subcommand structure…").
✏️ Proposed fix
-Enhanced help documentation sync test to verify subcommand structure and improve test maintainability +Enhance help documentation sync test to verify subcommand structure and improve test maintainabilityBased on learnings: "Provide a concise, single-line changeset summary in imperative mood (e.g., 'Add feature X', 'Fix bug Y') that describes what changed from a user/consumer perspective."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.changeset/help-sync-test-enhancements.md at line 5, Change the changeset summary from past tense to imperative mood: replace "Enhanced help documentation sync test to verify subcommand structure and improve test maintainability" with "Enhance help documentation sync test to verify subcommand structure and improve test maintainability" in the .changeset help-sync-test-enhancements.md summary line.apps/cli/tests/unit/help-documentation-sync.spec.ts (3)
74-77:console.warnleaks diagnostic output into test runner even on success.When the modern commands directory doesn't exist, this
console.warnwill print on every test run. Consider using a vitest spy or simply returning an empty array silently. If the warning is important for debugging, gate it behind a check that only warns when the directory is expected to exist.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/cli/tests/unit/help-documentation-sync.spec.ts` around lines 74 - 77, Replace the direct console.warn in the catch block that reads "Could not read modern commands directory" to avoid leaking output into the test runner: in the try/catch inside help-documentation-sync.spec.ts remove the console.warn and simply return an empty array (or otherwise proceed silently) when the directory is absent; alternatively, if the warning is useful for debugging keep a conditional or use a vitest spy on console.warn in the test harness to control when the message is emitted. This change targets the catch block handling "error" for the modern commands directory read so that tests no longer print diagnostics on successful runs.
361-397: Regex[^}]+}for isolating list command entries is fragile.
/name:\s*['"]list['"][^}]+}/gon lines 373 and 406 matches fromname: 'list'to the first}. If the list command object contains nested objects (e.g.,options: { ... }), the match will terminate prematurely at the inner closing brace, potentially missing documented options. A balanced-brace or section-isolation approach would be more robust.Also applies to: 399-427
119-140: Consider adding a comment or assertion to catch stale entries inINTENTIONALLY_UNDOCUMENTED.As commands are removed from the codebase over time, entries here can become stale without anyone noticing. A lightweight check (e.g., verifying each undocumented command still exists in
cliCommands) would keep this list honest and prevent it from becoming a catch-all that silently masks missing documentation.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/cli/tests/unit/help-documentation-sync.spec.ts` around lines 119 - 140, Add a lightweight assertion in the test that verifies every symbol in INTENTIONALLY_UNDOCUMENTED still corresponds to an existing command in the runtime command registry (e.g., the cliCommands collection used by the test); iterate INTENTIONALLY_UNDOCUMENTED and for each entry assert that cliCommands has/finds a command with that name, failing the test with a clear message if any entry is stale or missing. Ensure the assertion uses the same identifiers (INTENTIONALLY_UNDOCUMENTED and cliCommands) so future diffs will catch removed commands and prompt updating the list.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/tm-core/src/modules/loop/services/loop.service.ts`:
- Around line 586-590: The error-handling branch checking error.code ===
'ENOENT' returns a user-facing message; update the non-sandbox message to rename
the CLI to "Claude Code CLI" and point the URL to Anthropic's
getting-started/install page (use the getting-started install-specific link
instead of the overview). Modify the string returned in the error.code ===
'ENOENT' branch (the ternary that depends on the sandbox variable) so the
non-sandbox arm reads something like "Claude Code CLI is not installed. Install
it from: <Anthropic getting-started/install URL>" to match
src/ai-providers/claude-code.js and documentation naming.
---
Duplicate comments:
In `@src/ai-providers/claude-code.js`:
- Around line 86-93: The warning string in claude-code.js uses the less-helpful
overview URL; update the URL in the log call (the log('warn', ...) inside the
block that sets _claudeCliChecked = true) to point to a more direct
install/setup page (e.g. replace
https://docs.anthropic.com/en/docs/claude-code/overview with a getting-started
or setup path such as .../claude-code/getting-started or .../claude-code/setup)
so users land on installation steps; modify the message passed to log
accordingly and leave the surrounding try/finally and _claudeCliChecked logic
unchanged.
---
Nitpick comments:
In @.changeset/help-sync-test-enhancements.md:
- Line 5: Change the changeset summary from past tense to imperative mood:
replace "Enhanced help documentation sync test to verify subcommand structure
and improve test maintainability" with "Enhance help documentation sync test to
verify subcommand structure and improve test maintainability" in the .changeset
help-sync-test-enhancements.md summary line.
In `@apps/cli/tests/unit/help-documentation-sync.spec.ts`:
- Around line 74-77: Replace the direct console.warn in the catch block that
reads "Could not read modern commands directory" to avoid leaking output into
the test runner: in the try/catch inside help-documentation-sync.spec.ts remove
the console.warn and simply return an empty array (or otherwise proceed
silently) when the directory is absent; alternatively, if the warning is useful
for debugging keep a conditional or use a vitest spy on console.warn in the test
harness to control when the message is emitted. This change targets the catch
block handling "error" for the modern commands directory read so that tests no
longer print diagnostics on successful runs.
- Around line 119-140: Add a lightweight assertion in the test that verifies
every symbol in INTENTIONALLY_UNDOCUMENTED still corresponds to an existing
command in the runtime command registry (e.g., the cliCommands collection used
by the test); iterate INTENTIONALLY_UNDOCUMENTED and for each entry assert that
cliCommands has/finds a command with that name, failing the test with a clear
message if any entry is stale or missing. Ensure the assertion uses the same
identifiers (INTENTIONALLY_UNDOCUMENTED and cliCommands) so future diffs will
catch removed commands and prompt updating the list.
In `@docs/examples/claude-code-usage.md`:
- Around line 62-65: The install instructions currently only show the POSIX
installer command "curl -fsSL https://claude.ai/install.sh | bash"; add a
Windows (PowerShell) alternative by appending a short labeled section (e.g.,
"**Windows (PowerShell):**") and include the PowerShell installer command "irm
https://claude.ai/install.ps1 | iex", ensuring the platform split is clear to
Windows users and placed next to the existing bash example.
Address CodeRabbit review feedback: - Use /getting-started URL instead of /overview for install links - Rename "Claude CLI" to "Claude Code CLI" for consistency Fix false warning when running as MCP server with minimal PATH: - Fall back to checking common install locations (~/.local/bin, ~/.bun/bin, /usr/local/bin) when PATH-based lookup fails
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/ai-providers/claude-code.js`:
- Line 14: Replace use of execSync with execFileSync: update the import to use
execFileSync and change calls that currently interpolate the executable/path
into a template literal (the call that uses the variable found) to
execFileSync(executablePath, [found, ...args], { encoding: 'utf8' }) so the path
is passed as an argument instead of through a shell; ensure you pass the
executable (e.g., the Claude binary) as the first parameter and the found path
as an element in the args array, preserve existing error handling and options,
and apply the same conversion to any other execSync invocations that build shell
strings using found.
- Use execFileSync instead of execSync with template literal to avoid shell injection risk (CodeRabbit) - Add found binary's directory to process.env.PATH so the SDK can resolve it via PATH lookup downstream (Cursor Bugbot)
There was a problem hiding this comment.
🧹 Nitpick comments (2)
src/ai-providers/claude-code.js (2)
92-96:commonPathsis Unix-only despite a Windows PATH-separator guard on line 106.The
process.platform === 'win32'check at line 106 signals intent to support Windows, butcommonPathscontains only Unix paths. On Windows,existsSyncwill returnfalsefor all three entries, so the fallback discovery always fails silently. Consider either adding common Windows install locations or restricting the entire block to non-Windows platforms.♻️ Proposed fix
const commonPaths = [ join(home, '.local', 'bin', 'claude'), join(home, '.bun', 'bin', 'claude'), '/usr/local/bin/claude' ]; +// Windows equivalents (Claude installer typically places the binary here) +if (process.platform === 'win32') { + commonPaths.push( + join(process.env.LOCALAPPDATA || '', 'Programs', 'Claude', 'claude.exe'), + join(process.env.APPDATA || '', 'Claude', 'claude.exe') + ); +}🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/ai-providers/claude-code.js` around lines 92 - 96, The array commonPaths currently lists only Unix-style locations, so on Windows the subsequent process.platform === 'win32' guard is contradicted and existsSync will never find the binary; update the discovery in claude-code.js by either (a) adding common Windows install paths to commonPaths (e.g., include %LOCALAPPDATA%/Programs, %USERPROFILE%/AppData/Local/bin or typical installer locations) and expand join(home, ...) usage for Windows, or (b) wrap the Unix-style commonPaths block in a non-Windows conditional and add a separate Windows-only path array used when process.platform === 'win32'; adjust the existsSync checks (and any join usage) to use the appropriate array based on process.platform so discovery works on Windows and Unix.
118-118: Duplicate docs URL — extract to a module-level constant.The same URL literal appears on both line 118 and line 181. A single constant eliminates the risk of a future update touching one site but not the other.
♻️ Proposed refactor
+const CLAUDE_CODE_DOCS_URL = + 'https://docs.anthropic.com/en/docs/claude-code/getting-started'; + let _claudeCliChecked = false; let _claudeCliAvailable = null;- 'Claude Code CLI not detected. Install it from: https://docs.anthropic.com/en/docs/claude-code/getting-started' + `Claude Code CLI not detected. Install it from: ${CLAUDE_CODE_DOCS_URL}`- `Claude Code CLI not available. Install it from: https://docs.anthropic.com/en/docs/claude-code/getting-started - Original error: ${error.message}` + `Claude Code CLI not available. Install it from: ${CLAUDE_CODE_DOCS_URL} - Original error: ${error.message}`Also applies to: 181-181
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/ai-providers/claude-code.js` at line 118, There are two identical URL string literals for the Claude Code docs in src/ai-providers/claude-code.js; extract the URL into a single module-level constant (e.g., const CLAUDE_CODE_DOCS_URL = 'https://docs.anthropic.com/en/docs/claude-code/getting-started') declared at the top of the file and replace the literal occurrences inside the messages (the one in the 'Claude Code CLI not detected...' message and the second occurrence near line 181) with that constant so both locations reference the same value.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@src/ai-providers/claude-code.js`:
- Around line 92-96: The array commonPaths currently lists only Unix-style
locations, so on Windows the subsequent process.platform === 'win32' guard is
contradicted and existsSync will never find the binary; update the discovery in
claude-code.js by either (a) adding common Windows install paths to commonPaths
(e.g., include %LOCALAPPDATA%/Programs, %USERPROFILE%/AppData/Local/bin or
typical installer locations) and expand join(home, ...) usage for Windows, or
(b) wrap the Unix-style commonPaths block in a non-Windows conditional and add a
separate Windows-only path array used when process.platform === 'win32'; adjust
the existsSync checks (and any join usage) to use the appropriate array based on
process.platform so discovery works on Windows and Unix.
- Line 118: There are two identical URL string literals for the Claude Code docs
in src/ai-providers/claude-code.js; extract the URL into a single module-level
constant (e.g., const CLAUDE_CODE_DOCS_URL =
'https://docs.anthropic.com/en/docs/claude-code/getting-started') declared at
the top of the file and replace the literal occurrences inside the messages (the
one in the 'Claude Code CLI not detected...' message and the second occurrence
near line 181) with that constant so both locations reference the same value.
|
#1629 looks related |
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.
| join(home, '.local', 'bin', 'claude'), | ||
| join(home, '.bun', 'bin', 'claude'), | ||
| '/usr/local/bin/claude' | ||
| ]; |
There was a problem hiding this comment.
Missing Homebrew Apple Silicon path in fallback detection
Medium Severity
The commonPaths array for fallback CLI detection is missing /opt/homebrew/bin/claude, which is the standard Homebrew install location on Apple Silicon Macs. This is a very common platform among developers. The codebase itself already accounts for this path elsewhere (e.g., mcpClient.ts checks /opt/homebrew/bin/npx for "Homebrew on Apple Silicon"). In minimal PATH environments like MCP servers — the exact scenario this fallback targets — the CLI won't be detected for these users.
2 participants
Summary
curl -fsSL https://claude.ai/install.sh | bashor platform package managers) rather than vianpm install -g @anthropic-ai/claude-codeChanges Made
src/ai-providers/claude-code.js- Updated CLI detection warning and initialization error messages to link to official docspackages/tm-core/src/modules/loop/services/loop.service.ts- Updated loop service ENOENT error messagedocs/examples/claude-code-usage.md- Updated Requirements section with current install methodTest plan
Closes #1634
Note
Low Risk
Small, localized changes to CLI detection and user messaging; primary risk is false-positive/negative detection from the added path probing.
Overview
Fixes Claude Code CLI discovery when the
claudebinary isn’t onPATH(e.g., minimal MCP server environments) by probing common native install locations and temporarily extendingPATHwhen found.Updates user-facing docs and runtime error/warning messages to point to Anthropic’s official Claude Code install/getting-started documentation (and switches the example install command to the
curl ... | bashinstaller). Adds a patch changeset for the release.Written by Cursor Bugbot for commit f6eb5ae. This will update automatically on new commits. Configure here.
Summary by CodeRabbit
Documentation
Bug Fixes