mirror of https://github.com/SuperClaude-Org/SuperClaude_Framework.git synced 2025-12-17 17:56:46 +00:00

* 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

* 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>

2025-09-26 19:37:34 +05:30

2.9 KiB

Raw Blame History

SuperClaude Troubleshooting Guide 🔧

Quick fixes to advanced diagnostics for SuperClaude Framework issues.

Quick Fixes (90% of problems)

Installation Verification:

python3 -m SuperClaude --version    # Should show 4.1.5
SuperClaude install --list-components

Command Issues:

# 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:

# 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:

# 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:

python3 -m SuperClaude install --components core commands agents modes --force

Command Issues

Commands Not Recognized:

Restart Claude Code completely
Verify: python3 -m SuperClaude --version
Test: /sc:brainstorm "test"

Agents Not Activating:

Use specific keywords: /sc:implement "secure JWT authentication"
Manual activation: @agent-security "review auth code"

Slow Performance:

/sc:analyze . --no-mcp               # Test without MCP servers
/sc:analyze src/ --scope file        # Limit scope

MCP Server Issues

Server Connection Fails:

ls ~/.claude/.claude.json            # Check config exists
node --version                       # Verify Node.js 16+
SuperClaude install --components mcp --force

API Key Required (Magic/Morphllm):

export TWENTYFIRST_API_KEY="your_key"
export MORPH_API_KEY="your_key"
# Or use: /sc:command --no-mcp

Advanced Diagnostics

System Analysis:

SuperClaude install --diagnose
cat ~/.claude/logs/superclaude.log | tail -50

Component Analysis:

ls -la ~/.claude/                    # Check installed files
grep -r "@" ~/.claude/CLAUDE.md      # Verify imports

Reset Installation:

SuperClaude backup --create          # Backup first
SuperClaude uninstall
SuperClaude install --fresh

Get Help

Documentation:

Installation Guide - Setup issues
Commands Guide - Usage issues

Community:

GitHub Issues
Include: OS, Python version, error message, steps to reproduce

2.9 KiB Raw Blame History