claude-mpm 3.4.10__py3-none-any.whl → 5.4.55__py3-none-any.whl

claude_mpm/scripts/claude-hook-handler.sh

@@ -0,0 +1,227 @@
+#!/bin/bash
+#
+# Claude MPM Hook Handler Entry Point Script
+#
+# OVERVIEW:
+# This script serves as the bridge between Claude Code hook system and the Python-based
+# Claude MPM hook handler. It is executed directly by Claude Code when events occur
+# and ensures proper environment setup before delegating to the Python handler.
+#
+# ARCHITECTURE:
+# Claude Code → This Script → Python Environment → hook_handler.py → Socket.IO/EventBus
+#
+# KEY RESPONSIBILITIES:
+# - Virtual environment detection and activation
+# - Python executable resolution with fallbacks
+# - Error handling and logging for troubleshooting
+# - Path resolution for cross-platform compatibility
+# - Environment variable propagation
+#
+# DEPLOYMENT:
+# This script is deployed to Claude Code's hooks directory during installation.
+# Location: ~/.claude/hooks/claude-mpm/claude-hook-handler.sh
+# Permissions: Must be executable (chmod +x)
+#
+# ENVIRONMENT VARIABLES:
+# - CLAUDE_MPM_HOOK_DEBUG: Enable debug logging to /tmp/claude-mpm-hook.log
+# - CLAUDE_MPM_ROOT: Override project root detection
+# - VIRTUAL_ENV: Standard virtual environment variable
+# - PYTHONPATH: Extended with src/ directory for imports
+#
+# PERFORMANCE CONSIDERATIONS:
+# - Minimal shell operations to reduce latency (~10ms overhead)
+# - Cached virtual environment detection
+# - Early exit on errors to prevent hanging
+# - Lightweight logging for debugging without performance impact
+#
+# SECURITY:
+# - Restricts Python execution to project virtual environments
+# - Validates paths before execution
+# - No external network access or privileged operations
+# - Logs to temporary files only (no persistent sensitive data)
+#
+# TROUBLESHOOTING:
+# Enable debug logging: export CLAUDE_MPM_HOOK_DEBUG=true
+# Check permissions: ls -la ~/.claude/hooks/claude-mpm/claude-hook-handler.sh
+# Test manually: echo '{"test": "data"}' | ./claude-hook-handler.sh
+#
+# GOTCHAS:
+# - Must activate virtual environment in same shell process
+# - Path resolution differs between development and installed environments
+# - Claude Code passes event data via stdin (not command line arguments)
+# - Exit codes must be 0 for success, non-zero indicates failure to Claude Code
+#
+# @author Claude MPM Development Team
+# @version 1.0
+# @since v4.0.25
+
+# Exit on any error
+set -e
+
+# Get the directory where this script is located
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Determine the claude-mpm root based on installation type
+# Check if we're in a pipx installation
+if [[ "$SCRIPT_DIR" == *"/.local/pipx/venvs/claude-mpm/"* ]]; then
+    # pipx installation - script is at lib/python*/site-packages/claude_mpm/scripts/
+    # The venv root is what we need for Python detection
+    CLAUDE_MPM_ROOT="$(echo "$SCRIPT_DIR" | sed 's|/lib/python.*/site-packages/.*||')"
+elif [[ "$SCRIPT_DIR" == *"/site-packages/claude_mpm/scripts"* ]]; then
+    # Regular pip installation - script is in site-packages
+    # Use the Python environment root
+    CLAUDE_MPM_ROOT="$(python3 -c 'import sys; print(sys.prefix)')"
+else
+    # Development installation - script is at src/claude_mpm/scripts/, so we go up 3 levels
+    CLAUDE_MPM_ROOT="$(cd "$SCRIPT_DIR/../../.." 2>/dev/null && pwd || echo "$SCRIPT_DIR")"
+fi
+
+# Debug logging (can be enabled via environment variable)
+if [ "${CLAUDE_MPM_HOOK_DEBUG}" = "true" ]; then
+    echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Claude hook handler starting..." >> /tmp/claude-mpm-hook.log
+    echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Script dir: $SCRIPT_DIR" >> /tmp/claude-mpm-hook.log
+    echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Claude MPM root: $CLAUDE_MPM_ROOT" >> /tmp/claude-mpm-hook.log
+fi
+
+#
+# Find and return the appropriate Python executable for hook processing.
+#
+# STRATEGY:
+# This function implements a fallback chain to find Python with claude-mpm dependencies:
+# 1. UV-managed projects (uv.lock detected) - uses "uv run python"
+# 2. pipx installations - uses pipx venv Python
+# 3. Project-specific virtual environments (venv, .venv)
+# 4. Currently active virtual environment ($VIRTUAL_ENV)
+# 5. System python3 (may lack dependencies)
+# 6. System python (last resort)
+#
+# WHY THIS APPROACH:
+# - Claude MPM requires specific packages (socketio, eventlet) not in system Python
+# - UV and virtual environments ensure dependency isolation and availability
+# - Multiple naming conventions supported (venv vs .venv)
+# - Graceful degradation to system Python if no venv found
+#
+# ACTIVATION STRATEGY:
+# - UV projects: use "uv run python" to execute in UV-managed environment
+# - Sources activate script to set up environment variables
+# - Returns specific Python path for exec (not just 'python')
+# - Maintains environment in same shell process
+#
+# PERFORMANCE:
+# - Fast path detection using file existence checks
+# - Early returns to minimize overhead
+# - Caches result in process environment
+#
+# RETURNS:
+# Absolute path to Python executable with claude-mpm dependencies, or "uv run python" for UV projects
+#
+find_python_command() {
+    # 1. Check for UV project first (uv.lock or pyproject.toml with uv)
+    if [ -f "$CLAUDE_MPM_ROOT/uv.lock" ]; then
+        if command -v uv &> /dev/null; then
+            echo "uv run python"
+            return
+        fi
+    fi
+
+    # 2. Check if we're in a pipx installation
+    if [[ "$SCRIPT_DIR" == *"/.local/pipx/venvs/claude-mpm/"* ]]; then
+        # pipx installation - use the pipx venv's Python directly
+        if [ -f "$CLAUDE_MPM_ROOT/bin/python" ]; then
+            echo "$CLAUDE_MPM_ROOT/bin/python"
+            return
+        fi
+    fi
+
+    # 3. Check for project-local virtual environment (common in development)
+    if [ -f "$CLAUDE_MPM_ROOT/venv/bin/activate" ]; then
+        source "$CLAUDE_MPM_ROOT/venv/bin/activate"
+        echo "$CLAUDE_MPM_ROOT/venv/bin/python"
+    elif [ -f "$CLAUDE_MPM_ROOT/.venv/bin/activate" ]; then
+        source "$CLAUDE_MPM_ROOT/.venv/bin/activate"
+        echo "$CLAUDE_MPM_ROOT/.venv/bin/python"
+    elif [ -n "$VIRTUAL_ENV" ]; then
+        # Already in a virtual environment
+        echo "$VIRTUAL_ENV/bin/python"
+    elif command -v python3 &> /dev/null; then
+        echo "python3"
+    else
+        echo "python"
+    fi
+}
+
+# Set up Python command
+PYTHON_CMD=$(find_python_command)
+
+# Check installation type and set PYTHONPATH accordingly
+if [[ "$SCRIPT_DIR" == *"/.local/pipx/venvs/claude-mpm/"* ]]; then
+    # pipx installation - claude_mpm is already in the venv's site-packages
+    # No need to modify PYTHONPATH
+    if [ "${CLAUDE_MPM_HOOK_DEBUG}" = "true" ]; then
+        echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] pipx installation detected" >> /tmp/claude-mpm-hook.log
+    fi
+elif [ -d "$CLAUDE_MPM_ROOT/src" ]; then
+    # Development install - add src to PYTHONPATH
+    export PYTHONPATH="$CLAUDE_MPM_ROOT/src:$PYTHONPATH"
+
+    if [ "${CLAUDE_MPM_HOOK_DEBUG}" = "true" ]; then
+        echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Development environment detected" >> /tmp/claude-mpm-hook.log
+    fi
+else
+    # Regular pip install - claude_mpm should be in site-packages
+    # No need to modify PYTHONPATH
+    if [ "${CLAUDE_MPM_HOOK_DEBUG}" = "true" ]; then
+        echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Pip installation detected" >> /tmp/claude-mpm-hook.log
+    fi
+fi
+
+# Debug logging
+if [ "${CLAUDE_MPM_HOOK_DEBUG}" = "true" ]; then
+    echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] PYTHON_CMD: $PYTHON_CMD" >> /tmp/claude-mpm-hook.log
+    echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] PYTHONPATH: $PYTHONPATH" >> /tmp/claude-mpm-hook.log
+fi
+
+# Set Socket.IO configuration for hook events
+export CLAUDE_MPM_SOCKETIO_PORT="${CLAUDE_MPM_SOCKETIO_PORT:-8765}"
+
+# Function for debug logging
+log_debug() {
+    if [ "${CLAUDE_MPM_HOOK_DEBUG}" = "true" ]; then
+        echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] $1" >> /tmp/claude-mpm-hook.log
+    fi
+}
+
+# Test Python works and module exists
+# Handle UV's multi-word command specially
+if [[ "$PYTHON_CMD" == "uv run python" ]]; then
+    if ! uv run python -c "import claude_mpm" 2>/dev/null; then
+        log_debug "claude_mpm module not available, continuing without hook"
+        echo '{"action": "continue"}'
+        exit 0
+    fi
+else
+    if ! $PYTHON_CMD -c "import claude_mpm" 2>/dev/null; then
+        log_debug "claude_mpm module not available, continuing without hook"
+        echo '{"action": "continue"}'
+        exit 0
+    fi
+fi
+
+# Run the Python hook handler with all input
+# Use exec to replace the shell process with Python
+# Handle UV's multi-word command specially
+if [[ "$PYTHON_CMD" == "uv run python" ]]; then
+    exec uv run python -m claude_mpm.hooks.claude_hooks.hook_handler "$@" 2>/tmp/claude-mpm-hook-error.log
+else
+    exec "$PYTHON_CMD" -m claude_mpm.hooks.claude_hooks.hook_handler "$@" 2>/tmp/claude-mpm-hook-error.log
+fi
+
+# Note: exec replaces the shell process, so code below only runs if exec fails
+# If we reach here, the Python handler failed
+if [ "${CLAUDE_MPM_HOOK_DEBUG}" = "true" ]; then
+    echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Hook handler failed, see /tmp/claude-mpm-hook-error.log" >> /tmp/claude-mpm-hook.log
+    echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Error: $(cat /tmp/claude-mpm-hook-error.log 2>/dev/null | head -5)" >> /tmp/claude-mpm-hook.log
+fi
+# Return continue action to prevent blocking Claude Code
+echo '{"action": "continue"}'
+exit 0

claude_mpm/scripts/launch_monitor.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""
+Launch Monitor Script for Claude MPM.
+
+This script provides the entry point for launching the Claude MPM monitor
+dashboard, which includes both the Socket.IO server and web interface.
+
+WHY: Provides a simple command to start the monitoring dashboard that tracks
+Claude MPM events and agent activity in real-time.
+
+SINGLE INSTANCE ENFORCEMENT:
+- Only ONE monitor instance runs at a time on port 8765 (default)
+- If monitor already running on default port: reuse existing, open browser
+- If user specifies --port explicitly: use that port, fail if busy
+- No auto-increment port selection (prevents multiple instances)
+"""
+
+import argparse
+import sys
+import webbrowser
+
+from claude_mpm.core.logging_config import get_logger
+from claude_mpm.services.monitor.daemon import UnifiedMonitorDaemon
+from claude_mpm.services.monitor.daemon_manager import DaemonManager
+
+DEFAULT_PORT = 8765
+logger = get_logger(__name__)
+
+
+def check_existing_monitor(host: str, port: int) -> bool:
+    """Check if monitor is already running on the specified port.
+
+    Args:
+        host: Host to check
+        port: Port to check
+
+    Returns:
+        True if monitor is running, False otherwise
+    """
+    try:
+        import requests
+
+        response = requests.get(f"http://{host}:{port}/health", timeout=2)
+        if response.status_code == 200:
+            data = response.json()
+            # Check if it's our claude-mpm-monitor service
+            if data.get("service") == "claude-mpm-monitor":
+                return True
+    except Exception:
+        pass
+    return False
+
+
+def main():
+    """Main entry point for monitor launcher."""
+    parser = argparse.ArgumentParser(
+        description="Launch Claude MPM monitoring dashboard"
+    )
+
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=None,  # Changed: None means use DEFAULT_PORT with single-instance check
+        help=f"Port to run on (default: {DEFAULT_PORT}). If specified, fails if port is busy.",
+    )
+
+    parser.add_argument(
+        "--host", default="localhost", help="Host to bind to (default: localhost)"
+    )
+
+    parser.add_argument(
+        "--no-browser", action="store_true", help="Do not open browser automatically"
+    )
+
+    parser.add_argument(
+        "--background", action="store_true", help="Run in background daemon mode"
+    )
+
+    parser.add_argument(
+        "--dev",
+        action="store_true",
+        help="Enable development mode with hot reload for Svelte changes",
+    )
+
+    args = parser.parse_args()
+
+    # Determine target port
+    user_specified_port = args.port is not None
+    target_port = args.port if user_specified_port else DEFAULT_PORT
+
+    # SINGLE INSTANCE ENFORCEMENT:
+    # Check if monitor already running on target port
+    if check_existing_monitor(args.host, target_port):
+        logger.info(f"Monitor already running at http://{args.host}:{target_port}")
+
+        # Open browser to existing instance if requested
+        if not args.no_browser:
+            url = f"http://{args.host}:{target_port}"
+            logger.info(f"Opening browser to existing instance: {url}")
+            webbrowser.open(url)
+
+        # Success - reusing existing instance
+        return
+
+    # Port selection logic:
+    # - If user specified --port: Use that exact port, fail if busy
+    # - If no --port: Use DEFAULT_PORT (8765), fail if busy
+    # - Never auto-increment to find free port
+
+    # Create daemon manager for port checking
+    daemon_manager = DaemonManager(port=target_port, host=args.host)
+
+    if not daemon_manager._is_port_available():
+        if user_specified_port:
+            # User explicitly requested a port - fail with clear message
+            logger.error(
+                f"Port {target_port} is already in use by another service. "
+                f"Please stop the existing service or choose a different port."
+            )
+            sys.exit(1)
+        else:
+            # Default port is busy - fail with helpful message
+            logger.error(
+                f"Default port {DEFAULT_PORT} is already in use by another service. "
+                f"Please stop the existing service with 'claude-mpm monitor stop' "
+                f"or specify a different port with --port."
+            )
+            sys.exit(1)
+
+    # Start the monitor daemon
+    if args.dev:
+        logger.info(
+            f"Starting Claude MPM monitor on {args.host}:{target_port} (DEV MODE - hot reload enabled)"
+        )
+    else:
+        logger.info(f"Starting Claude MPM monitor on {args.host}:{target_port}")
+
+    daemon = UnifiedMonitorDaemon(
+        host=args.host,
+        port=target_port,
+        daemon_mode=args.background,
+        enable_hot_reload=args.dev,
+    )
+
+    success = daemon.start()
+
+    if success:
+        # Open browser if requested
+        if not args.no_browser:
+            url = f"http://{args.host}:{target_port}"
+            logger.info(f"Opening browser to {url}")
+            webbrowser.open(url)
+
+        if args.background:
+            logger.info(f"Monitor daemon started in background on port {target_port}")
+        else:
+            logger.info(f"Monitor running on port {target_port}")
+            logger.info("Press Ctrl+C to stop")
+    else:
+        logger.error("Failed to start monitor")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()