Bug: Critical conflicts when installing from multiple sources (npm, pip, plugin)

[Utakata]

Overview

Installing SuperClaude through multiple channels simultaneously—such as npm, Python (pip), and the Claude Code Plugin Marketplace—creates several critical conflicts. This leads to an unstable and unpredictable environment, negatively impacting user experience and the tool's reliability.

Key Conflicts

1. Version Mismatch 😭

Each installation method provides a different version of SuperClaude, causing inconsistencies and potential feature incompatibility. This can lead to older commands being executed or version-incompatible features being called.

• npm version: 4.1.5
• Python (pip) version: 4.1.6
• Claude Code Plugin version: 4.2.0

2. Configuration & Core File Overwrites 😱

All installation methods target the same core directory (~/.claude/) for configuration and framework files. The last method used to install or update will overwrite existing files, potentially corrupting or resetting the user's setup without warning.

Affected files include:

• ~/.claude/CLAUDE.md: The main entry point.
• ~/.claude/*.md: Files defining AI behavior.
• ~/.claude/claude-code-settings.json: Configuration for MCP servers and other settings.

3. Command Path Collision 🤯

Each installation adds a SuperClaude or superclaude executable to the system's PATH. The shell will execute whichever command appears first in the PATH's search order, which may not be the version the user intends to run. This ambiguity makes debugging and consistent operation extremely difficult.

4. Redundant Installation Scripts 😵‍💫

The npm package includes a post-install script that attempts to install SuperClaude via pip. If a pip-based installation already exists, this script can cause unexpected errors, permission issues, or corrupt the existing installation.

Conflict Flow Diagram

The following diagram illustrates how multiple installation sources compete for the same system resources, leading to instability.

graph TD
    subgraph Installation Methods
        A["npm install superclaude <br>(v4.1.5)"]
        B["pip install superclaude <br>(v4.1.6)"]
        C["Plugin Marketplace Install <br>(v4.2.0)"]
    end

    subgraph System Resources
        D["~/.claude/ (Config Directory)"]
        E["System PATH (`superclaude` command)"]
    end

    A -- "Writes/Overwrites" --> D;
    B -- "Writes/Overwrites" --> D;
    C -- "Writes/Overwrites" --> D;

    A -- "Registers command" --> E;
    B -- "Registers command" --> E;
    C -- "Registers command" --> E;

    subgraph Resulting Problems
        F["😭 Version Mismatch"]
        G["😱 Config Overwritten"]
        H["🤯 Command Conflict"]
        I["😵‍💫 Redundant Script Execution"]
    end

    D --> G;
    E --> H;
    A --- B & C --> F;
    A -- "triggers pip install" --> I;

Loading