claude-mpm 5.0.9__py3-none-any.whl → 5.6.23__py3-none-any.whl

claude_mpm/init.py

@@ -141,25 +141,6 @@ class ProjectInitializer:
             if not gitignore.exists():
                 gitignore.write_text("logs/\n*.log\n*.pyc\n__pycache__/\n")
 
-            # Also ensure MCP directories are in main project .gitignore
-            try:
-                from claude_mpm.services.project.project_organizer import (
-                    ProjectOrganizer,
-                )
-
-                # Check if we're in a git repository
-                if (project_root / ".git").exists():
-                    organizer = ProjectOrganizer(project_root)
-                    # This will add MCP directories and other standard patterns
-                    organizer.update_gitignore()
-                    self.logger.debug(
-                        "Updated project .gitignore with MCP and standard patterns"
-                    )
-            except Exception as e:
-                self.logger.debug(
-                    f"Could not update project gitignore with MCP patterns: {e}"
-                )
-
             # Log successful creation with details
             self.logger.info(f"Initialized project directory at {self.project_dir}")
             self.logger.debug("Created directories: agents, config, responses, logs")
@@ -182,6 +163,15 @@ class ProjectInitializer:
                         f"✓ Found {agent_count} project agent(s) in .claude-mpm/agents/"
                     )
 
+            # Verify and deploy PM skills (non-blocking)
+            self._verify_and_deploy_pm_skills(project_root, is_mcp_mode)
+
+            # Setup security hooks (auto-install pre-commit, detect-secrets)
+            self._setup_security_hooks(project_root, is_mcp_mode)
+
+            # Perform security checks (non-blocking)
+            self._check_security_risks(project_root, is_mcp_mode)
+
             return True
 
         except Exception as e:
@@ -189,6 +179,68 @@ class ProjectInitializer:
             print(f"✗ Failed to create .claude-mpm/ directory: {e}")
             return False
 
+    def _verify_and_deploy_pm_skills(
+        self, project_root: Path, is_mcp_mode: bool = False
+    ) -> None:
+        """Verify PM skills are deployed and auto-deploy if missing.
+
+        Non-blocking operation that gracefully handles errors.
+
+        Args:
+            project_root: Project root directory
+            is_mcp_mode: Whether running in MCP mode (suppress console output)
+        """
+        try:
+            from claude_mpm.services.pm_skills_deployer import PMSkillsDeployerService
+
+            deployer = PMSkillsDeployerService()
+            result = deployer.verify_pm_skills(project_root)
+
+            if not result.verified:
+                # Log warnings
+                for warning in result.warnings:
+                    self.logger.warning(warning)
+
+                # Auto-deploy PM skills
+                self.logger.info("Auto-deploying PM skills...")
+                deploy_result = deployer.deploy_pm_skills(project_root)
+
+                if deploy_result.success:
+                    self.logger.info(
+                        f"PM skills deployed: {len(deploy_result.deployed)} deployed, "
+                        f"{len(deploy_result.skipped)} skipped"
+                    )
+
+                    # Print to console if not in MCP mode
+                    if not is_mcp_mode:
+                        if deploy_result.deployed:
+                            print(
+                                f"✓ Deployed {len(deploy_result.deployed)} PM skill(s) "
+                                f"to .claude/skills/"
+                            )
+                else:
+                    self.logger.warning(
+                        f"PM skills deployment had errors: {len(deploy_result.errors)}"
+                    )
+                    if not is_mcp_mode and deploy_result.errors:
+                        print(
+                            f"⚠ PM skills deployment had {len(deploy_result.errors)} error(s)"
+                        )
+            else:
+                # Skills verified successfully
+                registry = deployer._load_registry(project_root)
+                skill_count = len(registry.get("skills", []))
+                self.logger.debug(f"PM skills verified: {skill_count} skills")
+
+                if not is_mcp_mode and skill_count > 0:
+                    print(f"✓ Verified {skill_count} PM skill(s)")
+
+        except ImportError:
+            self.logger.debug("PM skills deployer not available")
+        except Exception as e:
+            self.logger.warning(f"PM skills verification failed: {e}")
+            # Don't print to console - this is a non-critical failure
+
     def _migrate_project_agents(self):
         """Migrate agents from old subdirectory structure to direct agents directory.
 
@@ -338,6 +390,211 @@ class ProjectInitializer:
                 if not dst_file.exists():
                     shutil.copy2(template_file, dst_file)
 
+    def _setup_security_hooks(
+        self, project_root: Path, is_mcp_mode: bool = False
+    ) -> None:
+        """Automatically install pre-commit hooks for secret scanning.
+
+        This method:
+        1. Installs pre-commit and detect-secrets if missing
+        2. Copies .pre-commit-config.yaml to project root
+        3. Runs pre-commit install to set up git hooks
+        4. Creates .secrets.baseline for detect-secrets
+
+        Args:
+            project_root: Project root directory
+            is_mcp_mode: Whether running in MCP mode (suppress console output)
+        """
+        try:
+            import subprocess
+
+            # Only set up hooks if this is a git repository
+            if not (project_root / ".git").exists():
+                self.logger.debug("Not a git repository, skipping security hooks setup")
+                return
+
+            # Check/install pre-commit
+            try:
+                subprocess.run(
+                    ["pre-commit", "--version"],
+                    capture_output=True,
+                    text=True,
+                    timeout=2,
+                    check=True,
+                )
+            except (
+                subprocess.CalledProcessError,
+                subprocess.TimeoutExpired,
+                FileNotFoundError,
+            ):
+                self.logger.info("Installing pre-commit...")
+                try:
+                    subprocess.run(
+                        [sys.executable, "-m", "pip", "install", "pre-commit"],
+                        capture_output=True,
+                        text=True,
+                        timeout=60,
+                        check=True,
+                    )
+                    self.logger.info("pre-commit installed successfully")
+                except subprocess.CalledProcessError as e:
+                    self.logger.warning(f"Failed to install pre-commit: {e}")
+                    return
+
+            # Check/install detect-secrets
+            try:
+                subprocess.run(
+                    ["detect-secrets", "--version"],
+                    capture_output=True,
+                    text=True,
+                    timeout=2,
+                    check=True,
+                )
+            except (
+                subprocess.CalledProcessError,
+                subprocess.TimeoutExpired,
+                FileNotFoundError,
+            ):
+                self.logger.info("Installing detect-secrets...")
+                try:
+                    subprocess.run(
+                        [sys.executable, "-m", "pip", "install", "detect-secrets"],
+                        capture_output=True,
+                        text=True,
+                        timeout=60,
+                        check=True,
+                    )
+                    self.logger.info("detect-secrets installed successfully")
+                except subprocess.CalledProcessError as e:
+                    self.logger.warning(f"Failed to install detect-secrets: {e}")
+                    return
+
+            # Copy .pre-commit-config.yaml to project root if it doesn't exist
+            precommit_config = project_root / ".pre-commit-config.yaml"
+            if not precommit_config.exists():
+                template_dir = Path(__file__).parent / "templates"
+                template_config = template_dir / ".pre-commit-config.yaml"
+
+                if template_config.exists():
+                    shutil.copy2(template_config, precommit_config)
+                    self.logger.info("Copied .pre-commit-config.yaml to project root")
+                else:
+                    self.logger.warning("Template .pre-commit-config.yaml not found")
+                    return
+
+            # Create .secrets.baseline if it doesn't exist
+            secrets_baseline = project_root / ".secrets.baseline"
+            if not secrets_baseline.exists():
+                try:
+                    subprocess.run(
+                        ["detect-secrets", "scan", "--baseline", ".secrets.baseline"],
+                        cwd=str(project_root),
+                        capture_output=True,
+                        text=True,
+                        timeout=30,
+                        check=True,
+                    )
+                    self.logger.info("Created .secrets.baseline")
+                except subprocess.CalledProcessError as e:
+                    self.logger.warning(f"Failed to create .secrets.baseline: {e}")
+
+            # Install git hooks
+            try:
+                subprocess.run(
+                    ["pre-commit", "install"],
+                    cwd=str(project_root),
+                    capture_output=True,
+                    text=True,
+                    timeout=30,
+                    check=True,
+                )
+                self.logger.info("Pre-commit hooks installed in git repository")
+
+                if not is_mcp_mode:
+                    print("✓ Security hooks installed (pre-commit + detect-secrets)")
+
+            except subprocess.CalledProcessError as e:
+                self.logger.warning(f"Failed to install pre-commit hooks: {e}")
+
+        except Exception as e:
+            self.logger.debug(f"Security hooks setup failed: {e}")
+            # Don't print to console - this is a non-critical failure
+
+    def _check_security_risks(
+        self, project_root: Path, is_mcp_mode: bool = False
+    ) -> None:
+        """Check for potential security risks like exposed config files.
+
+        Non-blocking operation that warns about security issues.
+
+        Args:
+            project_root: Project root directory
+            is_mcp_mode: Whether running in MCP mode (suppress console output)
+        """
+        try:
+            import subprocess
+
+            security_issues = []
+
+            # Common secret file patterns to check
+            secret_patterns = [
+                ".mcp-vector-search/config.json",
+                ".mcp/config.json",
+                "openrouter.json",
+                "anthropic-config.json",
+                "credentials.json",
+                "secrets.json",
+                "api-keys.json",
+            ]
+
+            for pattern in secret_patterns:
+                file_path = project_root / pattern
+                if file_path.exists():
+                    # Check if file is tracked by git
+                    try:
+                        result = subprocess.run(
+                            ["git", "ls-files", str(file_path)],
+                            check=False,
+                            cwd=str(project_root),
+                            capture_output=True,
+                            text=True,
+                            timeout=2,
+                        )
+                        if result.stdout.strip():
+                            security_issues.append(
+                                f"⚠️  SECURITY: {pattern} is tracked by git (may contain secrets)"
+                            )
+                    except (subprocess.TimeoutExpired, FileNotFoundError):
+                        pass
+
+                    # Check if file is ignored by .gitignore
+                    try:
+                        result = subprocess.run(
+                            ["git", "check-ignore", str(file_path)],
+                            check=False,
+                            cwd=str(project_root),
+                            capture_output=True,
+                            text=True,
+                            timeout=2,
+                        )
+                        if result.returncode != 0:  # File NOT ignored
+                            security_issues.append(
+                                f"⚠️  WARNING: {pattern} exists but not in .gitignore"
+                            )
+                    except (subprocess.TimeoutExpired, FileNotFoundError):
+                        pass
+
+            # Print security warnings if not in MCP mode
+            if security_issues and not is_mcp_mode:
+                print("\n🔒 Security Check:")
+                for issue in security_issues:
+                    print(f"   {issue}")
+                print()
+
+        except Exception as e:
+            self.logger.debug(f"Security check failed: {e}")
+            # Don't print to console - this is a non-critical failure
+
     def validate_dependencies(self) -> Dict[str, bool]:
         """Validate that all required dependencies are available."""
         dependencies = {}

claude_mpm/models/agent_definition.py

@@ -103,6 +103,10 @@ class AgentMetadata:
     author: Optional[str] = None
     tags: List[str] = field(default_factory=list)
     specializations: List[str] = field(default_factory=list)
+    # NEW: Collection metadata for enhanced agent matching
+    collection_id: Optional[str] = None  # Format: owner/repo-name
+    source_path: Optional[str] = None  # Relative path in repository
+    canonical_id: Optional[str] = None  # Format: collection_id:agent_id
 
     def increment_serial_version(self) -> None:
         """Increment the patch version number.
@@ -181,6 +185,9 @@ class AgentDefinition:
                 "author": self.metadata.author,
                 "tags": self.metadata.tags,
                 "specializations": self.metadata.specializations,
+                "collection_id": self.metadata.collection_id,
+                "source_path": self.metadata.source_path,
+                "canonical_id": self.metadata.canonical_id,
             },
             "primary_role": self.primary_role,
             "when_to_use": self.when_to_use,

claude_mpm/models/git_repository.py

@@ -34,7 +34,7 @@ class GitRepository:
     def cache_path(self) -> Path:
         """Return cache directory path for this repository.
 
-        Cache structure: ~/.claude-mpm/cache/remote-agents/{owner}/{repo}/{subdirectory}/
+        Cache structure: ~/.claude-mpm/cache/agents/{owner}/{repo}/{subdirectory}/
 
         Returns:
             Absolute path to cache directory for this repository
@@ -45,10 +45,10 @@ class GitRepository:
             ...     subdirectory="agents"
             ... )
             >>> repo.cache_path
-            Path('/Users/user/.claude-mpm/cache/remote-agents/bobmatnyc/claude-mpm-agents/agents')
+            Path('/Users/user/.claude-mpm/cache/agents/bobmatnyc/claude-mpm-agents/agents')
         """
         home = Path.home()
-        base_cache = home / ".claude-mpm" / "cache" / "remote-agents"
+        base_cache = home / ".claude-mpm" / "cache" / "agents"
 
         # Extract owner and repo from URL
         owner, repo = self._parse_github_url(self.url)

claude_mpm/scripts/claude-hook-handler.sh

@@ -62,8 +62,13 @@ set -e
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # Determine the claude-mpm root based on installation type
+# Check if we're in a UV tools installation
+if [[ "$SCRIPT_DIR" == *"/.local/share/uv/tools/"* ]]; then
+    # UV tools installation - script is at lib/python*/site-packages/claude_mpm/scripts/
+    # The tool root is what we need for Python detection
+    CLAUDE_MPM_ROOT="$(echo "$SCRIPT_DIR" | sed 's|/lib/python.*/site-packages.*||')"
 # Check if we're in a pipx installation
-if [[ "$SCRIPT_DIR" == *"/.local/pipx/venvs/claude-mpm/"* ]]; then
+elif [[ "$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/.*||')"
@@ -88,18 +93,22 @@ fi
 #
 # STRATEGY:
 # This function implements a fallback chain to find Python with claude-mpm dependencies:
-# 1. Project-specific virtual environments (venv, .venv)
-# 2. Currently active virtual environment ($VIRTUAL_ENV)
-# 3. System python3 (may lack dependencies)
-# 4. System python (last resort)
+# 1. UV-managed projects (uv.lock detected) - uses "uv run python"
+# 2. UV tools installations (~/.local/share/uv/tools/) - uses tool's venv Python
+# 3. pipx installations - uses pipx venv Python
+# 4. Project-specific virtual environments (venv, .venv)
+# 5. Currently active virtual environment ($VIRTUAL_ENV)
+# 6. System python3 (may lack dependencies)
+# 7. System python (last resort)
 #
 # WHY THIS APPROACH:
 # - Claude MPM requires specific packages (socketio, eventlet) not in system Python
-# - Virtual environments ensure dependency isolation and availability
+# - 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
@@ -110,10 +119,32 @@ fi
 # - Caches result in process environment
 #
 # RETURNS:
-# Absolute path to Python executable with claude-mpm dependencies
+# Absolute path to Python executable with claude-mpm dependencies, or "uv run python" for UV projects
 #
 find_python_command() {
-    # 1. Check if we're in a pipx installation first
+    # 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 --directory \"$CLAUDE_MPM_ROOT\" python"
+            return
+        fi
+    fi
+
+    # 2. Check if we're in a UV tools installation
+    if [[ "$SCRIPT_DIR" == *"/.local/share/uv/tools/"* ]]; then
+        # UV tools installation - extract the tool root directory
+        CLAUDE_MPM_ROOT="$(echo "$SCRIPT_DIR" | sed 's|/lib/python.*/site-packages.*||')"
+        local uv_python="$CLAUDE_MPM_ROOT/bin/python"
+        if [ -x "$uv_python" ]; then
+            if [ "${CLAUDE_MPM_HOOK_DEBUG}" = "true" ]; then
+                echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] UV tools Python found: $uv_python" >> /tmp/claude-mpm-hook.log
+            fi
+            echo "$uv_python"
+            return
+        fi
+    fi
+
+    # 3. 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
@@ -122,7 +153,7 @@ find_python_command() {
         fi
     fi
 
-    # 2. Check for project-local virtual environment (common in development)
+    # 4. 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"
@@ -143,7 +174,13 @@ find_python_command() {
 PYTHON_CMD=$(find_python_command)
 
 # Check installation type and set PYTHONPATH accordingly
-if [[ "$SCRIPT_DIR" == *"/.local/pipx/venvs/claude-mpm/"* ]]; then
+if [[ "$SCRIPT_DIR" == *"/.local/share/uv/tools/"* ]]; then
+    # UV tools installation - claude_mpm is already in the tool'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)] UV tools installation detected" >> /tmp/claude-mpm-hook.log
+    fi
+elif [[ "$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
@@ -173,15 +210,45 @@ fi
 # Set Socket.IO configuration for hook events
 export CLAUDE_MPM_SOCKETIO_PORT="${CLAUDE_MPM_SOCKETIO_PORT:-8765}"
 
-# Run the Python hook handler with all input
-# Use exec to replace the shell process with Python
-if ! exec "$PYTHON_CMD" -m claude_mpm.hooks.claude_hooks.hook_handler "$@" 2>/tmp/claude-mpm-hook-error.log; then
-    # If the Python handler fails, always return continue to not block Claude
+# Function for debug logging
+log_debug() {
     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
+        echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] $1" >> /tmp/claude-mpm-hook.log
     fi
-    # Return continue action to prevent blocking Claude Code
-    echo '{"action": "continue"}'
-    exit 0
-fi
+}
+
+# Test Python works and module exists
+# Handle UV's multi-word command specially
+if [[ "$PYTHON_CMD" == "uv run"* ]]; then
+    if ! uv run --directory "$CLAUDE_MPM_ROOT" 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
+# Suppress RuntimeWarning to prevent stderr output (which causes hook errors)
+if [[ "$PYTHON_CMD" == "uv run"* ]]; then
+    exec uv run --directory "$CLAUDE_MPM_ROOT" python -W ignore::RuntimeWarning -m claude_mpm.hooks.claude_hooks.hook_handler "$@" 2>/tmp/claude-mpm-hook-error.log
+else
+    exec "$PYTHON_CMD" -W ignore::RuntimeWarning -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

@@ -7,6 +7,12 @@ 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
@@ -15,12 +21,36 @@ import webbrowser
 
 from claude_mpm.core.logging_config import get_logger
 from claude_mpm.services.monitor.daemon import UnifiedMonitorDaemon
-from claude_mpm.services.port_manager import PortManager
+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(
@@ -30,8 +60,8 @@ def main():
     parser.add_argument(
         "--port",
         type=int,
-        default=DEFAULT_PORT,
-        help=f"Port to run on (default: {DEFAULT_PORT})",
+        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(
@@ -46,20 +76,70 @@ def main():
         "--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()
 
-    # Find available port
-    port_manager = PortManager()
-    actual_port = port_manager.find_available_port(preferred_port=args.port)
+    # 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}")
 
-    if actual_port != args.port:
-        logger.info(f"Port {args.port} is in use, using port {actual_port} instead")
+        # 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
-    logger.info(f"Starting Claude MPM monitor on {args.host}:{actual_port}")
+    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=actual_port, daemon_mode=args.background
+        host=args.host,
+        port=target_port,
+        daemon_mode=args.background,
+        enable_hot_reload=args.dev,
     )
 
     success = daemon.start()
@@ -67,14 +147,14 @@ def main():
     if success:
         # Open browser if requested
         if not args.no_browser:
-            url = f"http://{args.host}:{actual_port}"
+            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 {actual_port}")
+            logger.info(f"Monitor daemon started in background on port {target_port}")
         else:
-            logger.info(f"Monitor running on port {actual_port}")
+            logger.info(f"Monitor running on port {target_port}")
             logger.info("Press Ctrl+C to stop")
     else:
         logger.error("Failed to start monitor")