mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
fdfb05e981
* The -i flag has been removed from the `_run_command_cross_platform` function in `setup/components/mcp.py`. * fix: Prevent installer from hanging during MCP installation The SuperClaude installer was hanging during the installation of MCP components on non-Windows systems. This was caused by the use of an interactive shell (`-i`) when executing the `claude mcp add` command. The interactive shell would attempt to read from standard input, causing the process to be suspended by the shell. This commit fixes the issue by removing the `-i` flag from the `_run_command_cross_platform` function in `setup/components/mcp.py`. This ensures that the installation process runs non-interactively and completes without hanging. * fix: Add 'cmd /c' for Windows and refactor shell execution This commit resolves an issue with `npx` command execution on Windows by prepending `cmd /c` to the command. It also refactors the shell command execution for non-Windows systems to use the `executable` argument in `subprocess.run` for a cleaner and more robust implementation. * fix: Add 'cmd /c' for Windows and refactor shell execution This commit resolves an issue with `npx` command execution on Windows by prepending `cmd /c` to the command. It also refactors the shell command execution for non-Windows systems to use the `executable` argument in `subprocess.run` for a cleaner and more robust implementation. * docs: Update Chrome DevTools MCP documentation This commit updates the documentation for the Chrome DevTools MCP server to be more comprehensive and consistent with the existing documentation structure. The file `SuperClaude/MCP/MCP_Chrome-DevTools.md` has been updated with detailed information about the server's purpose, triggers, and usage examples. * docs: Update documentation for Chrome DevTools MCP This commit updates the main README.md and the MCP servers user guide to include information about the new Chrome DevTools MCP server. The documentation has been updated to reflect the new server count and provide details about the new server's functionality. * chore: Bump version to 4.1.5 This commit updates the version number from 4.1.4 to 4.1.5 across the entire codebase. This includes updates to: - CHANGELOG.md - Documentation files - Configuration files (package.json, pyproject.toml) - Source code fallbacks - The main VERSION file --------- Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
124 lines
2.9 KiB
Markdown
124 lines
2.9 KiB
Markdown
# SuperClaude Troubleshooting Guide 🔧
|
|
|
|
Quick fixes to advanced diagnostics for SuperClaude Framework issues.
|
|
|
|
## Quick Fixes (90% of problems)
|
|
|
|
**Installation Verification:**
|
|
```bash
|
|
python3 -m SuperClaude --version # Should show 4.1.5
|
|
SuperClaude install --list-components
|
|
```
|
|
|
|
**Command Issues:**
|
|
```bash
|
|
# Test in Claude Code:
|
|
/sc:brainstorm "test project" # Should ask discovery questions
|
|
|
|
# If no response: Restart Claude Code session
|
|
```
|
|
|
|
**Resolution Checklist:**
|
|
- [ ] Version commands work and show 4.1.5
|
|
- [ ] `/sc:` commands respond in Claude Code
|
|
- [ ] MCP servers listed: `SuperClaude install --list-components | grep mcp`
|
|
|
|
## Common Issues
|
|
|
|
### Installation Problems
|
|
|
|
**Package Installation Fails:**
|
|
```bash
|
|
# For pipx users
|
|
pipx uninstall SuperClaude
|
|
pipx install SuperClaude
|
|
|
|
# For pip users
|
|
pip uninstall SuperClaude
|
|
pip install --upgrade pip
|
|
pip install SuperClaude
|
|
```
|
|
|
|
**Permission Denied / PEP 668 Error:**
|
|
```bash
|
|
# Option 1: Use pipx (recommended)
|
|
pipx install SuperClaude
|
|
|
|
# Option 2: Use pip with --user flag
|
|
pip install --user SuperClaude
|
|
|
|
# Option 3: Fix permissions
|
|
sudo chown -R $USER ~/.claude
|
|
|
|
# Option 4: Force installation (use with caution)
|
|
pip install --break-system-packages SuperClaude
|
|
```
|
|
|
|
**Component Missing:**
|
|
```bash
|
|
python3 -m SuperClaude install --components core commands agents modes --force
|
|
```
|
|
|
|
### Command Issues
|
|
|
|
**Commands Not Recognized:**
|
|
1. Restart Claude Code completely
|
|
2. Verify: `python3 -m SuperClaude --version`
|
|
3. Test: `/sc:brainstorm "test"`
|
|
|
|
**Agents Not Activating:**
|
|
- Use specific keywords: `/sc:implement "secure JWT authentication"`
|
|
- Manual activation: `@agent-security "review auth code"`
|
|
|
|
**Slow Performance:**
|
|
```bash
|
|
/sc:analyze . --no-mcp # Test without MCP servers
|
|
/sc:analyze src/ --scope file # Limit scope
|
|
```
|
|
|
|
### MCP Server Issues
|
|
|
|
**Server Connection Fails:**
|
|
```bash
|
|
ls ~/.claude/.claude.json # Check config exists
|
|
node --version # Verify Node.js 16+
|
|
SuperClaude install --components mcp --force
|
|
```
|
|
|
|
**API Key Required (Magic/Morphllm):**
|
|
```bash
|
|
export TWENTYFIRST_API_KEY="your_key"
|
|
export MORPH_API_KEY="your_key"
|
|
# Or use: /sc:command --no-mcp
|
|
```
|
|
|
|
## Advanced Diagnostics
|
|
|
|
**System Analysis:**
|
|
```bash
|
|
SuperClaude install --diagnose
|
|
cat ~/.claude/logs/superclaude.log | tail -50
|
|
```
|
|
|
|
**Component Analysis:**
|
|
```bash
|
|
ls -la ~/.claude/ # Check installed files
|
|
grep -r "@" ~/.claude/CLAUDE.md # Verify imports
|
|
```
|
|
|
|
**Reset Installation:**
|
|
```bash
|
|
SuperClaude backup --create # Backup first
|
|
SuperClaude uninstall
|
|
SuperClaude install --fresh
|
|
```
|
|
|
|
## Get Help
|
|
|
|
**Documentation:**
|
|
- [Installation Guide](../Getting-Started/installation.md) - Setup issues
|
|
- [Commands Guide](../User-Guide/commands.md) - Usage issues
|
|
|
|
**Community:**
|
|
- [GitHub Issues](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues)
|
|
- Include: OS, Python version, error message, steps to reproduce |