Skip to content

fix Claude Code install guidance#1697

Open
xianjianlf2 wants to merge 3 commits intoeyaltoledano:mainfrom
xianjianlf2:fix/claude-code-install-guidance
Open

fix Claude Code install guidance#1697
xianjianlf2 wants to merge 3 commits intoeyaltoledano:mainfrom
xianjianlf2:fix/claude-code-install-guidance

Conversation

@xianjianlf2
Copy link
Copy Markdown

@xianjianlf2 xianjianlf2 commented Apr 28, 2026

Summary

This PR updates Claude Code install guidance to point users to Anthropic's official setup docs instead of hard-coding a single install path.

What Changed

  • updated Claude Code CLI warning/error messages to use a shared official setup URL
  • aligned loop service ENOENT guidance with the same docs-first wording
  • removed the install-script example from the Claude Code usage example and linked directly to Anthropic's setup guide
  • tightened the Claude Code error-handling test to assert the new guidance
  • added a tm-core integration test covering the loop service install message
  • added a patch changeset for the user-facing fix

Why

The current guidance was inconsistent across the codebase and could go stale as Claude Code installation flows evolve. Pointing users to the official setup guide is more durable and avoids steering them to a single installation path.

Validation

  • npm run format-check
  • npm test -- tests/integration/claude-code-error-handling.test.js tests/unit/ai-providers/claude-code.test.js
  • ../../node_modules/.bin/vitest run --config vitest.config.ts --coverage.enabled=false tests/integration/loop/loop-service-error-messages.test.ts from packages/tm-core
  • npm run build
  • ./node_modules/.bin/cross-env NODE_ENV=test node --experimental-vm-modules node_modules/.bin/jest tests/integration/cli/complex-cross-tag-scenarios.test.js --runInBand

Notes

I also ran the repository-wide npm test, but there are unrelated pre-existing Jest ESM teardown failures in profile-related suites.

Closes #1634

Summary by CodeRabbit

  • Documentation

    • Referenced Anthropic’s official Claude Code setup guide in installation/authentication instructions and fixed trailing newline in an example.
  • Bug Fixes

    • Updated user-facing messages to direct users to the official Claude Code CLI setup documentation when the CLI is not detected.
  • Tests

    • Added integration tests to validate CLI-detection and sandbox-related error messages.

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented Apr 28, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 0471c598-937a-4ffc-83bb-03772dfc11c4

📥 Commits

Reviewing files that changed from the base of the PR and between 66891b5 and 1f29246.

📒 Files selected for processing (6)
  • .changeset/rare-badgers-ring.md
  • docs/examples/claude-code-usage.md
  • packages/tm-core/src/modules/loop/services/loop.service.ts
  • packages/tm-core/tests/integration/loop/loop-service-error-messages.test.ts
  • src/ai-providers/claude-code.js
  • tests/integration/claude-code-error-handling.test.js
✅ Files skipped from review due to trivial changes (2)
  • .changeset/rare-badgers-ring.md
  • docs/examples/claude-code-usage.md
🚧 Files skipped from review as they are similar to previous changes (3)
  • packages/tm-core/src/modules/loop/services/loop.service.ts
  • packages/tm-core/tests/integration/loop/loop-service-error-messages.test.ts
  • tests/integration/claude-code-error-handling.test.js

📝 Walkthrough

Walkthrough

Replaces npm-install guidance for the Claude Code CLI with a link to Anthropic’s official setup docs across docs and runtime messages; centralizes the setup URL constant and updates/adds integration tests to assert the revised messaging.

Changes

Cohort / File(s) Summary
Changeset
\.changeset/rare-badgers-ring.md
Adds a patch changeset recording the messaging/docs update for task-master-ai.
Documentation
docs/examples/claude-code-usage.md
Replaces npm install instruction with a link to Anthropic’s Claude Code setup docs and fixes trailing newline.
Claude Code Provider
src/ai-providers/claude-code.js
Adds CLAUDE_CODE_SETUP_URL constant and updates CLI-detection and initialization messages to point to the official setup guide instead of npm install text.
Loop Service
packages/tm-core/src/modules/loop/services/loop.service.ts
When CLI is missing (ENOENT) in non-sandbox mode, message now directs users to the official setup guide URL; sandbox/docker branches unchanged.
Tests
tests/integration/claude-code-error-handling.test.js, packages/tm-core/tests/integration/loop/loop-service-error-messages.test.ts
Strengthens/introduces tests asserting the new "official setup guide" wording and presence of the Anthropic docs URL for CLI-not-found scenarios (claude vs docker/sandbox).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

Suggested reviewers

  • eyaltoledano
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'fix Claude Code install guidance' directly and concisely summarizes the main objective: updating Claude Code CLI installation messages and documentation to reference Anthropic's official setup guide.
Linked Issues check ✅ Passed All coding requirements from issue #1634 are met: installation guidance updated in loop service error handling, ai-providers error/warning messages, documentation examples, and comprehensive tests added to validate the new guidance.
Out of Scope Changes check ✅ Passed All changes are directly related to issue #1634 objectives: updating Claude Code installation guidance across error messages, documentation, and adding corresponding tests. No extraneous modifications detected.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@changeset-bot
Copy link
Copy Markdown

changeset-bot Bot commented Apr 28, 2026

🦋 Changeset detected

Latest commit: 1f29246

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

@xianjianlf2 xianjianlf2 marked this pull request as ready for review April 28, 2026 07:36
@xianjianlf2 xianjianlf2 changed the title [codex] fix Claude Code install guidance fix Claude Code install guidance Apr 28, 2026
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 `@tests/integration/claude-code-error-handling.test.js`:
- Around line 34-35: The test currently asserts on the full, exact error text
(including the full URL) which is brittle; update the assertions in
tests/integration/claude-code-error-handling.test.js so they check for stable
semantics instead: replace the exact full-string match with looser checks such
as expect(error.message).toMatch(/Claude Code CLI not available/i) and a
separate assertion that the message contains the docs domain or path fragment
(e.g., expect(error.message).toContain('docs.anthropic.com') or
expect(error.message).toMatch(/getting-started/i)); update both assertions that
reference the exact phrase/URL so they verify intent and guidance presence
rather than the full literal text.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 10945f61-6273-43ea-bb1d-135fd610ae21

📥 Commits

Reviewing files that changed from the base of the PR and between 487c3d3 and c29197a.

📒 Files selected for processing (6)
  • .changeset/rare-badgers-ring.md
  • docs/examples/claude-code-usage.md
  • packages/tm-core/src/modules/loop/services/loop.service.ts
  • packages/tm-core/tests/integration/loop/loop-service-error-messages.test.ts
  • src/ai-providers/claude-code.js
  • tests/integration/claude-code-error-handling.test.js

Comment thread tests/integration/claude-code-error-handling.test.js Outdated
@Crunchyman-ralph Crunchyman-ralph changed the base branch from next to main April 28, 2026 12:31
@Crunchyman-ralph Crunchyman-ralph dismissed their stale review April 28, 2026 12:31

The base branch was changed.

@xianjianlf2 xianjianlf2 force-pushed the fix/claude-code-install-guidance branch from d4c4b67 to 1f29246 Compare April 28, 2026 18:59
@xianjianlf2
Copy link
Copy Markdown
Author

xianjianlf2 commented Apr 28, 2026

I force-pushed this PR after the base was changed to main.

The branch originally contained next-based history, which made the PR include a large unrelated diff when retargeted to main. I rebuilt it on top of main and kept only the three commits relevant to this Claude Code install-guidance fix, so the PR now reflects just the intended changes for main.

I also kept a backup of the previous branch state in backup/pr1697-before-main-cleanup in my fork in case we need to reference it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Outdated Claude Code CLI install instructions in warning/error messages

2 participants