claude-mpm 4.1.6__py3-none-any.whl → 4.24.0__py3-none-any.whl

claude_mpm/models/resume_log.py

@@ -0,0 +1,340 @@
+"""Resume Log Data Model.
+
+This module defines the data structure for session resume logs that enable
+seamless context restoration when Claude hits token limits.
+
+Design Philosophy:
+- Target 10k tokens maximum per resume log
+- Human-readable markdown format
+- Structured sections with token budgets
+- Optimized for Claude consumption on session resume
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from claude_mpm.core.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class ContextMetrics:
+    """Context window usage metrics."""
+
+    total_budget: int = 200000
+    used_tokens: int = 0
+    remaining_tokens: int = 0
+    percentage_used: float = 0.0
+    stop_reason: Optional[str] = None
+    model: str = "claude-sonnet-4.5"
+    session_id: str = ""
+    timestamp: str = field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "total_budget": self.total_budget,
+            "used_tokens": self.used_tokens,
+            "remaining_tokens": self.remaining_tokens,
+            "percentage_used": self.percentage_used,
+            "stop_reason": self.stop_reason,
+            "model": self.model,
+            "session_id": self.session_id,
+            "timestamp": self.timestamp,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ContextMetrics":
+        """Create from dictionary."""
+        return cls(
+            total_budget=data.get("total_budget", 200000),
+            used_tokens=data.get("used_tokens", 0),
+            remaining_tokens=data.get("remaining_tokens", 0),
+            percentage_used=data.get("percentage_used", 0.0),
+            stop_reason=data.get("stop_reason"),
+            model=data.get("model", "claude-sonnet-4.5"),
+            session_id=data.get("session_id", ""),
+            timestamp=data.get("timestamp", datetime.now(timezone.utc).isoformat()),
+        )
+
+
+@dataclass
+class ResumeLog:
+    """Resume log containing all information needed to restore session context.
+
+    Token Budget Distribution (10k tokens total):
+    - Context Metrics: 500 tokens
+    - Mission Summary: 1,000 tokens
+    - Accomplishments: 2,000 tokens
+    - Key Findings: 2,500 tokens
+    - Decisions & Rationale: 1,500 tokens
+    - Next Steps: 1,500 tokens
+    - Critical Context: 1,000 tokens
+    """
+
+    # Session identification
+    session_id: str
+    previous_session_id: Optional[str] = None
+    created_at: str = field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+
+    # Context metrics
+    context_metrics: ContextMetrics = field(default_factory=ContextMetrics)
+
+    # Core content sections (with token budgets)
+    mission_summary: str = ""  # 1,000 tokens - What was the overall goal?
+    accomplishments: List[str] = field(
+        default_factory=list
+    )  # 2,000 tokens - What was completed?
+    key_findings: List[str] = field(
+        default_factory=list
+    )  # 2,500 tokens - What was discovered?
+    decisions_made: List[Dict[str, str]] = field(
+        default_factory=list
+    )  # 1,500 tokens - What choices were made and why?
+    next_steps: List[str] = field(
+        default_factory=list
+    )  # 1,500 tokens - What needs to happen next?
+    critical_context: Dict[str, Any] = field(
+        default_factory=dict
+    )  # 1,000 tokens - Essential state/data
+
+    # Metadata
+    files_modified: List[str] = field(default_factory=list)
+    agents_used: Dict[str, int] = field(default_factory=dict)
+    errors_encountered: List[str] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+
+    def to_markdown(self) -> str:
+        """Generate markdown format for Claude consumption.
+
+        Returns:
+            Markdown-formatted resume log
+        """
+        sections = []
+
+        # Header
+        sections.append(f"# Session Resume Log: {self.session_id}\n")
+        sections.append(f"**Created**: {self.created_at}")
+        if self.previous_session_id:
+            sections.append(f"**Previous Session**: {self.previous_session_id}")
+        sections.append("")
+
+        # Context Metrics (500 tokens)
+        sections.append("## Context Metrics\n")
+        sections.append(f"- **Model**: {self.context_metrics.model}")
+        sections.append(
+            f"- **Tokens Used**: {self.context_metrics.used_tokens:,} / {self.context_metrics.total_budget:,}"
+        )
+        sections.append(
+            f"- **Percentage**: {self.context_metrics.percentage_used:.1f}%"
+        )
+        sections.append(
+            f"- **Remaining**: {self.context_metrics.remaining_tokens:,} tokens"
+        )
+        if self.context_metrics.stop_reason:
+            sections.append(f"- **Stop Reason**: {self.context_metrics.stop_reason}")
+        sections.append("")
+
+        # Mission Summary (1,000 tokens)
+        sections.append("## Mission Summary\n")
+        sections.append(
+            self.mission_summary
+            if self.mission_summary
+            else "_No mission summary provided_"
+        )
+        sections.append("")
+
+        # Accomplishments (2,000 tokens)
+        sections.append("## Accomplishments\n")
+        if self.accomplishments:
+            for i, item in enumerate(self.accomplishments, 1):
+                sections.append(f"{i}. {item}")
+        else:
+            sections.append("_No accomplishments recorded_")
+        sections.append("")
+
+        # Key Findings (2,500 tokens)
+        sections.append("## Key Findings\n")
+        if self.key_findings:
+            for i, finding in enumerate(self.key_findings, 1):
+                sections.append(f"{i}. {finding}")
+        else:
+            sections.append("_No key findings recorded_")
+        sections.append("")
+
+        # Decisions & Rationale (1,500 tokens)
+        sections.append("## Decisions & Rationale\n")
+        if self.decisions_made:
+            for i, decision in enumerate(self.decisions_made, 1):
+                decision_text = decision.get("decision", "")
+                rationale = decision.get("rationale", "")
+                sections.append(f"{i}. **Decision**: {decision_text}")
+                if rationale:
+                    sections.append(f"   **Rationale**: {rationale}")
+        else:
+            sections.append("_No decisions recorded_")
+        sections.append("")
+
+        # Next Steps (1,500 tokens)
+        sections.append("## Next Steps\n")
+        if self.next_steps:
+            for i, step in enumerate(self.next_steps, 1):
+                sections.append(f"{i}. {step}")
+        else:
+            sections.append("_No next steps defined_")
+        sections.append("")
+
+        # Critical Context (1,000 tokens)
+        sections.append("## Critical Context\n")
+        if self.critical_context:
+            for key, value in self.critical_context.items():
+                sections.append(f"- **{key}**: {value}")
+        else:
+            sections.append("_No critical context preserved_")
+        sections.append("")
+
+        # Metadata
+        sections.append("## Session Metadata\n")
+        if self.files_modified:
+            sections.append(f"**Files Modified** ({len(self.files_modified)}):")
+            for file in self.files_modified[:20]:  # Limit to first 20
+                sections.append(f"- {file}")
+            if len(self.files_modified) > 20:
+                sections.append(f"- ... and {len(self.files_modified) - 20} more")
+            sections.append("")
+
+        if self.agents_used:
+            sections.append("**Agents Used**:")
+            for agent, count in self.agents_used.items():
+                sections.append(f"- {agent}: {count} delegations")
+            sections.append("")
+
+        if self.errors_encountered:
+            sections.append(f"**Errors** ({len(self.errors_encountered)}):")
+            for error in self.errors_encountered[:5]:  # Limit to first 5
+                sections.append(f"- {error}")
+            sections.append("")
+
+        if self.warnings:
+            sections.append(f"**Warnings** ({len(self.warnings)}):")
+            for warning in self.warnings[:5]:  # Limit to first 5
+                sections.append(f"- {warning}")
+            sections.append("")
+
+        return "\n".join(sections)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "session_id": self.session_id,
+            "previous_session_id": self.previous_session_id,
+            "created_at": self.created_at,
+            "context_metrics": self.context_metrics.to_dict(),
+            "mission_summary": self.mission_summary,
+            "accomplishments": self.accomplishments,
+            "key_findings": self.key_findings,
+            "decisions_made": self.decisions_made,
+            "next_steps": self.next_steps,
+            "critical_context": self.critical_context,
+            "files_modified": self.files_modified,
+            "agents_used": self.agents_used,
+            "errors_encountered": self.errors_encountered,
+            "warnings": self.warnings,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ResumeLog":
+        """Create from dictionary."""
+        context_metrics_data = data.get("context_metrics", {})
+        context_metrics = ContextMetrics.from_dict(context_metrics_data)
+
+        return cls(
+            session_id=data.get("session_id", ""),
+            previous_session_id=data.get("previous_session_id"),
+            created_at=data.get("created_at", datetime.now(timezone.utc).isoformat()),
+            context_metrics=context_metrics,
+            mission_summary=data.get("mission_summary", ""),
+            accomplishments=data.get("accomplishments", []),
+            key_findings=data.get("key_findings", []),
+            decisions_made=data.get("decisions_made", []),
+            next_steps=data.get("next_steps", []),
+            critical_context=data.get("critical_context", {}),
+            files_modified=data.get("files_modified", []),
+            agents_used=data.get("agents_used", {}),
+            errors_encountered=data.get("errors_encountered", []),
+            warnings=data.get("warnings", []),
+        )
+
+    def save(self, storage_dir: Optional[Path] = None) -> Path:
+        """Save resume log to markdown file.
+
+        Args:
+            storage_dir: Directory to save the log (default: .claude-mpm/resume-logs)
+
+        Returns:
+            Path to saved file
+        """
+        if storage_dir is None:
+            storage_dir = Path.home() / ".claude-mpm" / "resume-logs"
+
+        storage_dir.mkdir(parents=True, exist_ok=True)
+
+        # Generate filename
+        file_path = storage_dir / f"session-{self.session_id}.md"
+
+        try:
+            # Write markdown file
+            markdown_content = self.to_markdown()
+            file_path.write_text(markdown_content, encoding="utf-8")
+
+            logger.info(f"Resume log saved: {file_path}")
+            return file_path
+
+        except Exception as e:
+            logger.error(f"Failed to save resume log: {e}")
+            raise
+
+    @classmethod
+    def load(
+        cls, session_id: str, storage_dir: Optional[Path] = None
+    ) -> Optional["ResumeLog"]:
+        """Load resume log from file.
+
+        Args:
+            session_id: Session ID to load
+            storage_dir: Directory to load from (default: .claude-mpm/resume-logs)
+
+        Returns:
+            ResumeLog instance or None if not found
+        """
+        if storage_dir is None:
+            storage_dir = Path.home() / ".claude-mpm" / "resume-logs"
+
+        file_path = storage_dir / f"session-{session_id}.md"
+
+        if not file_path.exists():
+            logger.debug(f"Resume log not found: {file_path}")
+            return None
+
+        try:
+            # For now, we just return the markdown content
+            # In the future, could parse markdown back to structured data
+            _ = file_path.read_text(encoding="utf-8")
+            logger.info(f"Resume log loaded: {file_path}")
+
+            # Return a basic ResumeLog with the markdown content embedded
+            return cls(
+                session_id=session_id,
+                mission_summary=f"Loaded from previous session. See full context in {file_path}",
+            )
+
+        except Exception as e:
+            logger.error(f"Failed to load resume log: {e}")
+            return None

claude_mpm/schemas/__init__.py

@@ -0,0 +1,12 @@
+"""
+Schemas package for Claude MPM.
+
+This package contains JSON schema files used for validation of agent
+configurations, frontmatter, and other structured data within Claude MPM.
+
+These schema files may be accessed via importlib.resources for validation
+purposes throughout the application.
+
+This __init__.py file is required to make this directory recognizable as a
+Python package by setuptools for proper distribution and resource access.
+"""

claude_mpm/scripts/claude-hook-handler.sh

@@ -0,0 +1,187 @@
+#!/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. Project-specific virtual environments (venv, .venv)
+# 2. Currently active virtual environment ($VIRTUAL_ENV)  
+# 3. System python3 (may lack dependencies)
+# 4. 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
+# - Multiple naming conventions supported (venv vs .venv)
+# - Graceful degradation to system Python if no venv found
+#
+# ACTIVATION STRATEGY:
+# - 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
+#
+find_python_command() {
+    # 1. Check if we're in a pipx installation first
+    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
+    
+    # 2. 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}"
+
+# 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
+    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
+fi

claude_mpm/scripts/launch_monitor.py

@@ -0,0 +1,85 @@
+#!/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.
+"""
+
+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.port_manager import PortManager
+
+DEFAULT_PORT = 8765
+logger = get_logger(__name__)
+
+
+def main():
+    """Main entry point for monitor launcher."""
+    parser = argparse.ArgumentParser(
+        description="Launch Claude MPM monitoring dashboard"
+    )
+
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=DEFAULT_PORT,
+        help=f"Port to run on (default: {DEFAULT_PORT})",
+    )
+
+    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"
+    )
+
+    args = parser.parse_args()
+
+    # Find available port
+    port_manager = PortManager()
+    actual_port = port_manager.find_available_port(preferred_port=args.port)
+
+    if actual_port != args.port:
+        logger.info(f"Port {args.port} is in use, using port {actual_port} instead")
+
+    # Start the monitor daemon
+    logger.info(f"Starting Claude MPM monitor on {args.host}:{actual_port}")
+
+    daemon = UnifiedMonitorDaemon(
+        host=args.host, port=actual_port, daemon_mode=args.background
+    )
+
+    success = daemon.start()
+
+    if success:
+        # Open browser if requested
+        if not args.no_browser:
+            url = f"http://{args.host}:{actual_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}")
+        else:
+            logger.info(f"Monitor running on port {actual_port}")
+            logger.info("Press Ctrl+C to stop")
+    else:
+        logger.error("Failed to start monitor")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

claude_mpm/scripts/mcp_server.py

@@ -6,15 +6,13 @@ It handles proper Python path setup and error reporting to stderr.
 """
 
 import logging
-import os
 import sys
+from pathlib import Path
 
 # Since we're now in src/claude_mpm/scripts/, we need to go up 3 levels to reach the project root
 # Then down into src to add it to the path
-project_root = os.path.abspath(
-    os.path.join(os.path.dirname(__file__), "..", "..", "..")
-)
-sys.path.insert(0, os.path.join(project_root, "src"))
+project_root = Path(Path(Path(__file__).parent.resolve().joinpath(), "..", "..", ".."))
+sys.path.insert(0, Path(project_root) / "src")
 
 
 def setup_logging():

claude_mpm/scripts/mpm_doctor.py

@@ -14,7 +14,6 @@ DESIGN DECISIONS:
 """
 
 import argparse
-import logging
 import sys
 from pathlib import Path
 from typing import Any, Dict, List, Optional
@@ -52,7 +51,9 @@ def run_diagnostics(
         - warning_count: int - number of warnings found
         - message: str - optional error message if failed
     """
-    logger = logging.getLogger(__name__)
+    from claude_mpm.core.logging_utils import get_logger
+
+    logger = get_logger(__name__)
 
     # Create diagnostic runner
     runner = DiagnosticRunner(verbose=verbose, fix=fix)