- 
                Notifications
    You must be signed in to change notification settings 
- Fork 3.7k
docs: Add claude PATH troubleshooting section #157
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Conversation
Fixes 'claude not found' error when Claude is installed but uvx cannot find it in PATH during subprocess execution.
There was a problem hiding this 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 | 
    
      
    
      Copilot
AI
    
    
    
      Sep 10, 2025 
    
  
There was a problem hiding this comment.
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.
| 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 | 
| **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` | 
    
      
    
      Copilot
AI
    
    
    
      Sep 10, 2025 
    
  
There was a problem hiding this comment.
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.
| **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` | 
| @petebytes should we make this a bit more generic for other CLI tools as well? | 
Summary
Problem
Users with Claude installed were encountering
⚠️ claude not founderrors when running: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:
Testing
All documented solutions were tested and verified to work correctly.