Proposal: Implement pre-install hook to prevent conflicts with existing installations

[Utakata]

Overview

To prevent potential version mismatches and configuration overwrites, this proposal outlines a plan to add a pre-install hook to the SuperClaude plugin. This hook will detect existing SuperClaude installations (from pip or npm) and prevent the plugin from installing if a conflict is found, thereby safeguarding the user's environment.

We will leverage the built-in hooking mechanism of the claude-code plugin system.

Implementation Details

The implementation consists of two main steps:

Step 1: Create a Conflict Check Script

First, we will create a new Python script responsible for detecting existing installations. This script will be placed in a hooks/ directory within the plugin.

File: .claude-plugin/hooks/check_conflict.py (New)

import subprocess
import sys
import shutil

def check_pip_install():
    """Checks if SuperClaude is installed via pip."""
    try:
        subprocess.check_output(["pip", "show", "SuperClaude"], stderr=subprocess.STDOUT)
        return True
    except subprocess.CalledProcessError:
        return False

def check_npm_install():
    """Checks if the superclaude command (installed via npm) exists in PATH."""
    return shutil.which("superclaude") is not None or shutil.which("SuperClaude") is not None

def main():
    pip_installed = check_pip_install()
    npm_installed = check_npm_install()

    if pip_installed or npm_installed:
        error_message = (
            "ERROR: A conflicting version of SuperClaude is already installed.\\n"
            "An existing installation was found from pip or npm.\\n"
            "Please uninstall it first to avoid conflicts.\\n"
            "  - To uninstall pip version: pip uninstall SuperClaude\\n"
            "  - To uninstall npm version: npm uninstall -g @bifrost_inc/superclaude"
        )
        # Write the error message to stderr
        sys.stderr.write(f"\\n🚨 {error_message}\\n\\n")
        # Exit with a non-zero status code to fail the installation
        sys.exit(1)

    # Exit with zero status code if no conflict is found
    sys.exit(0)

if __name__ == "__main__":
    main()

Step 2: Register the Hook
Next, we will register this script to run on the on-install event by creating a hooks.json file.

File: .claude-plugin/hooks.json (New)

{
  "hooks": [
    {
      "event": "on-install",
      "script": "hooks/check_conflict.py"
    }
  ]
}

(Note: The event name on-install is assumed based on the claude-code hook system, as seen in other plugins like security-guidance.)

Expected Behavior & Benefits ✨
With this hook in place, the installation process will be much safer:

A user attempts to install the SuperClaude plugin via the Claude Code UI.

The on-install event fires, executing check_conflict.py.

The script scans the system for existing pip or npm installations.

If a conflict is found, the script exits with an error code and prints a detailed message to the user.

Claude Code detects the script failure and aborts the plugin installation, displaying the error.

If no conflict is found, the script exits cleanly, and the installation proceeds as normal.

This proactive check effectively prevents issues like version conflicts and overwritten configuration files, making the repository safer and more robust for all users.

Process Flow Diagram

graph TD
    A[User clicks Install Plugin] --> B{Trigger 'on-install' event};
    B --> C[Execute hooks/check_conflict.py];
    C --> D{Scan for existing<br>pip/npm installations};
    D -- "Conflict Found" --> E[Write error to stderr];
    E --> F[Exit with status 1];
    F --> G[❌ Installation Aborted & Error Shown];
    D -- "No Conflict" --> H[Exit with status 0];
    H --> I[✅ Installation Proceeds];

Loading