Skip to content

Conversation

@petebytes
Copy link

Summary

  • Adds troubleshooting section for "claude not found" error when using uvx
  • Documents PATH-based solution for subprocess environments that don't inherit shell aliases
  • Includes alternative solutions for permanent PATH setup and symlinks

Problem

Users with Claude installed were encountering ⚠️ claude not found errors when running:

uvx --from git+https://github.com/github/spec-kit.git specify init --here

This occurs because uvx creates subprocess environments that don't inherit shell aliases, and claude is often installed in non-standard PATH locations.

Solution

Added concise troubleshooting section with:

  • Quick fix using PATH prefix
  • Alternative solutions for permanent setup
  • Clear indication this applies when Claude is installed but not found

Testing

All documented solutions were tested and verified to work correctly.

Fixes 'claude not found' error when Claude is installed but
uvx cannot find it in PATH during subprocess execution.
@petebytes petebytes requested a review from localden as a code owner September 10, 2025 20:20
Copilot AI review requested due to automatic review settings September 10, 2025 20:20
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull Request Overview

This PR adds a troubleshooting section to help users resolve "claude not found" errors when using uvx to run spec-kit commands. The issue occurs when Claude is installed but uvx subprocess environments don't inherit shell aliases or PATH configurations.

  • Adds dedicated troubleshooting section for Claude CLI PATH issues
  • Provides quick fix using PATH prefix and alternative permanent solutions
  • Documents the root cause as subprocess environments not inheriting shell configuration

Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.


**Quick fix:**
```bash
PATH="$HOME/.claude/local:$PATH" uvx --from git+https://github.com/github/spec-kit.git specify init --here
Copy link

Copilot AI Sep 10, 2025

Choose a reason for hiding this comment

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

The PATH assumes Claude is installed in $HOME/.claude/local, but this may not be accurate for all installations. Consider using a more generic example like PATH="/path/to/claude/directory:$PATH" or mention that users should replace with their actual Claude installation path.

Suggested change
PATH="$HOME/.claude/local:$PATH" uvx --from git+https://github.com/github/spec-kit.git specify init --here
# Replace /path/to/claude/directory with the actual path to your Claude installation
PATH="/path/to/claude/directory:$PATH" uvx --from git+https://github.com/github/spec-kit.git specify init --here

Copilot uses AI. Check for mistakes.
Comment on lines +58 to +66
**Quick fix:**
```bash
PATH="$HOME/.claude/local:$PATH" uvx --from git+https://github.com/github/spec-kit.git specify init --here
```

**Other solutions:**
- Find claude location: `which claude`
- Add to shell permanently: `export PATH="$HOME/.claude/local:$PATH"` in `~/.bashrc`/`~/.zshrc`
- Create symlink: `ln -s ~/.claude/local/claude /usr/local/bin/claude`
Copy link

Copilot AI Sep 10, 2025

Choose a reason for hiding this comment

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

Similar to the quick fix, this assumes a specific installation path. Consider clarifying that users should verify their actual Claude installation location first, or provide instructions on how to find it.

Suggested change
**Quick fix:**
```bash
PATH="$HOME/.claude/local:$PATH" uvx --from git+https://github.com/github/spec-kit.git specify init --here
```
**Other solutions:**
- Find claude location: `which claude`
- Add to shell permanently: `export PATH="$HOME/.claude/local:$PATH"` in `~/.bashrc`/`~/.zshrc`
- Create symlink: `ln -s ~/.claude/local/claude /usr/local/bin/claude`
**Quick fix (default path):**
> Note: The path `$HOME/.claude/local` is the default for some installations. Your Claude installation may be elsewhere.
> To find the actual location, run:
>
> ```bash
> which claude
> ```
>
> Then, update your PATH accordingly. For example, if `which claude` returns `/home/user/.claude/local/claude`, use:
>
> ```bash
> export PATH="/home/user/.claude/local:$PATH"
> ```
>
> You can run the initialization command after updating your PATH:
>
> ```bash
> uvx --from git+https://github.com/github/spec-kit.git specify init --here
> ```
**Other solutions:**
- Add to shell permanently: Add the export line above to your `~/.bashrc` or `~/.zshrc`
- Create symlink: `ln -s $(which claude) /usr/local/bin/claude`

Copilot uses AI. Check for mistakes.
@localden localden self-assigned this Sep 10, 2025
@localden localden added merge-candidate Reasonable change that is going to be merged after a review. documentation Improvements or additions to documentation labels Sep 10, 2025
@localden
Copy link
Collaborator

@petebytes should we make this a bit more generic for other CLI tools as well?

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

Labels

documentation Improvements or additions to documentation merge-candidate Reasonable change that is going to be merged after a review.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants