claude-mpm 4.0.28__py3-none-any.whl → 4.0.30__py3-none-any.whl

claude_mpm/cli/commands/doctor.py

@@ -0,0 +1,209 @@
+"""
+Doctor command implementation for claude-mpm.
+
+WHY: Provide a comprehensive diagnostic tool to help users identify and fix
+common issues with their claude-mpm installation and configuration.
+
+DESIGN DECISIONS:
+- Use diagnostic runner for orchestration
+- Support multiple output formats (terminal, JSON, markdown)
+- Provide verbose mode for detailed diagnostics
+- Future: Support --fix flag for automatic remediation
+"""
+
+import logging
+import sys
+from pathlib import Path
+
+from ...services.diagnostics import DiagnosticRunner, DoctorReporter
+
+
+def add_doctor_parser(subparsers):
+    """Add doctor command parser.
+    
+    WHY: This command helps users diagnose and fix issues with their
+    claude-mpm installation, providing clear actionable feedback.
+    """
+    parser = subparsers.add_parser(
+        "doctor",
+        aliases=["diagnose", "check-health"],
+        help="Run comprehensive diagnostics on claude-mpm installation",
+        description="Run comprehensive health checks on your claude-mpm installation and configuration"
+    )
+    
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Show detailed diagnostic information"
+    )
+    
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output results in JSON format"
+    )
+    
+    parser.add_argument(
+        "--markdown",
+        action="store_true",
+        help="Output results in Markdown format"
+    )
+    
+    parser.add_argument(
+        "--fix",
+        action="store_true",
+        help="Attempt to fix issues automatically (experimental)"
+    )
+    
+    parser.add_argument(
+        "--checks",
+        nargs="+",
+        choices=[
+            "installation", "configuration", "filesystem",
+            "claude", "agents", "mcp", "monitor", "common"
+        ],
+        help="Run only specific checks"
+    )
+    
+    parser.add_argument(
+        "--parallel",
+        action="store_true",
+        help="Run checks in parallel for faster execution"
+    )
+    
+    parser.add_argument(
+        "--no-color",
+        action="store_true",
+        help="Disable colored output"
+    )
+    
+    parser.add_argument(
+        "--output",
+        "-o",
+        type=Path,
+        help="Save output to file"
+    )
+    
+    parser.set_defaults(func=doctor_command)
+
+
+def run_doctor(args):
+    """Main entry point for doctor command (used by CLI).
+    
+    Args:
+        args: Parsed command-line arguments
+        
+    Returns:
+        Exit code (0 for success, 1 for warnings, 2 for errors)
+    """
+    return doctor_command(args)
+
+
+def doctor_command(args):
+    """Execute the doctor command.
+    
+    WHY: Provides a single entry point for system diagnostics, helping users
+    quickly identify and resolve issues with their claude-mpm setup.
+    
+    Args:
+        args: Parsed command-line arguments
+        
+    Returns:
+        Exit code (0 for success, 1 for warnings, 2 for errors)
+    """
+    # Configure logging
+    logger = logging.getLogger(__name__)
+    
+    # Determine output format
+    if args.json:
+        output_format = "json"
+    elif args.markdown:
+        output_format = "markdown"
+    else:
+        output_format = "terminal"
+    
+    # Create diagnostic runner
+    runner = DiagnosticRunner(
+        verbose=args.verbose,
+        fix=args.fix
+    )
+    
+    # Run diagnostics
+    try:
+        if args.checks:
+            # Run specific checks
+            logger.info(f"Running specific checks: {', '.join(args.checks)}")
+            summary = runner.run_specific_checks(args.checks)
+        elif args.parallel:
+            # Run all checks in parallel
+            logger.info("Running diagnostics in parallel mode")
+            summary = runner.run_diagnostics_parallel()
+        else:
+            # Run all checks sequentially
+            logger.info("Running comprehensive diagnostics")
+            summary = runner.run_diagnostics()
+    
+    except KeyboardInterrupt:
+        print("\nDiagnostics interrupted by user")
+        return 130
+    except Exception as e:
+        logger.error(f"Diagnostic failed: {e}")
+        print(f"\n❌ Diagnostic failed: {str(e)}")
+        if args.verbose:
+            import traceback
+            traceback.print_exc()
+        return 2
+    
+    # Create reporter
+    reporter = DoctorReporter(
+        use_color=not args.no_color,
+        verbose=args.verbose
+    )
+    
+    # Output results
+    if args.output:
+        # Save to file
+        try:
+            import sys
+            original_stdout = sys.stdout
+            with open(args.output, 'w') as f:
+                sys.stdout = f
+                reporter.report(summary, format=output_format)
+            sys.stdout = original_stdout
+            print(f"Report saved to: {args.output}")
+        except Exception as e:
+            logger.error(f"Failed to save report: {e}")
+            print(f"❌ Failed to save report: {str(e)}")
+            # Still output to terminal
+            reporter.report(summary, format=output_format)
+    else:
+        # Output to terminal
+        reporter.report(summary, format=output_format)
+    
+    # Determine exit code based on results
+    if summary.error_count > 0:
+        return 2  # Errors found
+    elif summary.warning_count > 0:
+        return 1  # Warnings found
+    else:
+        return 0  # All OK
+
+
+# Optional: Standalone execution for testing
+if __name__ == "__main__":
+    import argparse
+    
+    parser = argparse.ArgumentParser(description="Claude MPM Doctor")
+    parser.add_argument("--verbose", "-v", action="store_true")
+    parser.add_argument("--json", action="store_true")
+    parser.add_argument("--fix", action="store_true")
+    parser.add_argument("--no-color", action="store_true")
+    parser.add_argument("--checks", nargs="+")
+    parser.add_argument("--parallel", action="store_true")
+    
+    args = parser.parse_args()
+    args.markdown = False
+    args.output = None
+    
+    sys.exit(doctor_command(args))

claude_mpm/cli/commands/mcp.py

@@ -157,7 +157,7 @@ def _show_status(
     else:
         print(f"   No config file at {config_path}")
 
-    # Show Claude Desktop configuration
+    # Show Claude Code configuration
     claude_config = (
         Path.home()
         / "Library"
@@ -166,7 +166,7 @@ def _show_status(
         / "claude_desktop_config.json"
     )
     if claude_config.exists():
-        print(f"\n🖥️  Claude Desktop Config: {claude_config}")
+        print(f"\n🖥️  Claude Code Config: {claude_config}")
         try:
             with open(claude_config) as f:
                 config = json.load(f)
@@ -179,7 +179,7 @@ def _show_status(
         except Exception as e:
             print(f"   ⚠️  Error reading config: {e}")
     else:
-        print("\n🖥️  Claude Desktop not configured for MCP")
+        print("\n🖥️  Claude Code not configured for MCP")
         print("   Run: claude-mpm mcp start (for instructions)")
 
     # Show available tools count

claude_mpm/cli/commands/mcp_install_commands.py

@@ -159,48 +159,30 @@ class MCPInstallCommands:
 
         DESIGN DECISION: We prioritize in this order:
         1. System-installed claude-mpm (most reliable)
-        2. Virtual environment claude-mpm (development)
-        3. Python module invocation (fallback)
+        2. pipx-installed claude-mpm (detected via deployment context)
+        3. Virtual environment claude-mpm (development)
+        4. Python module invocation (fallback)
 
         Returns:
             str or None: Path to claude-mpm executable
         """
-        import shutil
         import sys
-        import os
-
-        # 1. Try to find claude-mpm in PATH (system-wide or venv)
-        claude_mpm_path = shutil.which("claude-mpm")
-        if claude_mpm_path:
-            print(f"   Found claude-mpm: {claude_mpm_path}")
-            return claude_mpm_path
-
-        # 2. Check if we're in a virtual environment
-        if hasattr(sys, 'real_prefix') or (hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix):
-            # We're in a virtual environment
-            venv_bin = Path(sys.prefix) / ("Scripts" if sys.platform == "win32" else "bin")
-            venv_claude_mpm = venv_bin / "claude-mpm"
-            if venv_claude_mpm.exists():
-                print(f"   Found claude-mpm in venv: {venv_claude_mpm}")
-                return str(venv_claude_mpm)
-
-        # 3. Check if claude_mpm module is installed and use Python to run it
+        from ...core.unified_paths import get_executable_path
+
+        # Use the enhanced unified path manager for executable detection
+        executable_path = get_executable_path()
+        if executable_path:
+            print(f"   Found claude-mpm: {executable_path}")
+            return str(executable_path)
+
+        # Fallback: Use Python module invocation if no executable found
         try:
             import claude_mpm
-            # Return the Python executable - we'll handle the -m args separately
             print(f"   Using Python module: {sys.executable} -m claude_mpm")
             return sys.executable
         except ImportError:
             pass
 
-        # 4. Last resort: check project's local venv (development mode)
-        project_root = Path(__file__).parent.parent.parent.parent.parent
-        local_venv_bin = project_root / "venv" / ("Scripts" if sys.platform == "win32" else "bin")
-        local_claude_mpm = local_venv_bin / "claude-mpm"
-        if local_claude_mpm.exists():
-            print(f"   Found claude-mpm in project venv: {local_claude_mpm}")
-            return str(local_claude_mpm)
-
         return None
 
     def _load_or_create_config(self, config_path, force=False):

claude_mpm/cli/commands/mcp_server_commands.py

@@ -22,11 +22,11 @@ class MCPServerCommands:
         """Start MCP server command.
 
         WHY: This command starts the MCP server using the proper stdio-based
-        implementation that Claude Desktop can communicate with.
-        NOTE: MCP is for Claude Desktop's Code features.
+        implementation that Claude Code can communicate with.
+        NOTE: MCP is specifically for Claude Code features.
 
         DESIGN DECISION: Run the server directly in the same process to ensure
-        Claude Desktop sees the correct command path, not a wrapper script.
+        Claude Code sees the correct command path, not a wrapper script.
         """
         self.logger.info("MCP server start command called")
 
@@ -39,18 +39,18 @@ class MCPServerCommands:
             # Daemon mode - not recommended for MCP
             print("⚠️  MCP servers are designed to be spawned by Claude Code")
             print("   Running as a daemon is not recommended.")
-            print("   Note: MCP is ONLY for Claude Code, not Claude Desktop.")
+            print("   Note: MCP is specifically for Claude Code.")
             return 1
 
         if show_instructions:
             # Show configuration instructions
-            print("🚀 MCP Server Setup Instructions for Claude Desktop")
+            print("🚀 MCP Server Setup Instructions for Claude Code")
             print("=" * 50)
-            print("\nThe MCP server enables Claude Desktop to use tools and integrations.")
+            print("\nThe MCP server enables Claude Code to use tools and integrations.")
             print("\nTo configure the MCP server:")
             print("\n1. Run the configuration script:")
             print("   python scripts/configure_mcp_server.py")
-            print("\n2. Or manually configure Claude Desktop:")
+            print("\n2. Or manually configure Claude Code:")
             
             # Find project root for paths
             project_root = Path(__file__).parent.parent.parent.parent.parent
@@ -62,7 +62,7 @@ class MCPServerCommands:
                 # Fallback to current executable
                 claude_mpm_path = sys.executable.replace("python", "claude-mpm")
             
-            print("\n   Add this to your Claude Desktop configuration:")
+            print("\n   Add this to your Claude Code configuration:")
             print("   (~/Library/Application Support/Claude/claude_desktop_config.json on macOS)")
             print("\n   {")
             print('     "mcpServers": {')
@@ -73,7 +73,7 @@ class MCPServerCommands:
             print('       }')
             print('     }')
             print('   }')
-            print("\n3. Restart Claude Desktop to load the MCP server")
+            print("\n3. Restart Claude Code to load the MCP server")
             print("\nTo test the server directly:")
             print("   claude-mpm mcp server")
             print("\nTo check running MCP processes:")

claude_mpm/cli/commands/memory.py

@@ -23,7 +23,7 @@ from ...core.config import Config
 from ...core.logger import get_logger
 from ...core.shared.config_loader import ConfigLoader
 from ...services.agents.memory import AgentMemoryManager
-from ..shared.command_base import MemoryCommand, CommandResult
+from ..shared.base_command import MemoryCommand, CommandResult
 from ..shared.argument_patterns import add_memory_arguments, add_output_arguments
 
 

claude_mpm/cli/commands/run.py

@@ -30,6 +30,11 @@ from ...core.unified_paths import get_package_root, get_scripts_dir
 from ...services.port_manager import PortManager
 from ...utils.dependency_manager import ensure_socketio_dependencies
 from ..shared import BaseCommand, CommandResult
+from ..startup_logging import (
+    log_startup_status, 
+    setup_startup_logging,
+    cleanup_old_startup_logs
+)
 from ..utils import get_user_input, list_agent_versions_at_startup
 
 
@@ -232,6 +237,12 @@ class RunCommand(BaseCommand):
             if args.logging != LogLevel.OFF.value:
                 self.logger.info("Starting Claude MPM session")
 
+            # Log MCP and monitor startup status
+            if args.logging != LogLevel.OFF.value:
+                monitor_mode = getattr(args, "monitor", False)
+                websocket_port = getattr(args, "websocket_port", 8765)
+                log_startup_status(monitor_mode, websocket_port)
+
             # Perform startup checks
             self._check_configuration_health()
             self._check_claude_json_memory(args)
@@ -549,9 +560,27 @@ def run_session_legacy(args):
     Args:
         args: Parsed command line arguments
     """
+    # Set up startup logging to file early in the process
+    startup_log_file = setup_startup_logging(Path.cwd())
+    
     logger = get_logger("cli")
     if args.logging != LogLevel.OFF.value:
         logger.info("Starting Claude MPM session")
+        logger.info(f"Startup log: {startup_log_file}")
+    
+    # Clean up old startup logs (keep last 7 days or minimum 10 files)
+    try:
+        deleted_count = cleanup_old_startup_logs(Path.cwd())
+        if deleted_count > 0:
+            logger.debug(f"Cleaned up {deleted_count} old startup log files")
+    except Exception as e:
+        logger.debug(f"Failed to clean up old logs: {e}")
+
+    # Log MCP and monitor startup status
+    if args.logging != LogLevel.OFF.value:
+        monitor_mode = getattr(args, "monitor", False)
+        websocket_port = getattr(args, "websocket_port", 8765)
+        log_startup_status(monitor_mode, websocket_port)
 
     # Perform startup configuration check
     _check_configuration_health(logger)
@@ -1102,7 +1131,7 @@ def _check_claude_json_memory(args, logger):
     """Check .claude.json file size and warn about memory issues.
 
     WHY: Large .claude.json files (>500KB) cause significant memory issues when
-    using --resume. Claude Desktop loads the entire conversation history into
+    using --resume. Claude Code loads the entire conversation history into
     memory, leading to 2GB+ memory consumption.
 
     DESIGN DECISIONS:
@@ -1159,7 +1188,7 @@ def _check_claude_json_memory(args, logger):
             f"\n⚠️  CRITICAL: Large .claude.json file detected ({format_size(file_size)})"
         )
         print(f"   This WILL cause memory issues when using --resume")
-        print(f"   Claude Desktop may consume 2GB+ of memory\n")
+        print(f"   Claude Code may consume 2GB+ of memory\n")
 
         if not getattr(args, "force", False):
             print("   Recommended actions:")

claude_mpm/cli/commands/run_config_checker.py

@@ -21,7 +21,7 @@ class RunConfigChecker:
         """Check .claude.json file size and warn about memory issues.
 
         WHY: Large .claude.json files (>500KB) cause significant memory issues when
-        using --resume. Claude Desktop loads the entire conversation history into
+        using --resume. Claude Code loads the entire conversation history into
         memory, leading to 2GB+ memory consumption.
         """
         try:

claude_mpm/cli/parsers/agent_manager_parser.py

@@ -0,0 +1,247 @@
+"""
+Agent Manager parser module for claude-mpm CLI.
+
+This module defines the argument parser for the agent-manager command,
+which provides comprehensive agent lifecycle management capabilities.
+"""
+
+import argparse
+
+
+def add_agent_manager_subparser(subparsers: argparse._SubParsersAction) -> None:
+    """
+    Add the agent-manager subcommand to the parser.
+    
+    Args:
+        subparsers: The subparsers object to add to
+    """
+    # Create the agent-manager parser
+    agent_manager_parser = subparsers.add_parser(
+        "agent-manager",
+        help="Manage agent creation, customization, and deployment",
+        description="Comprehensive agent lifecycle management for Claude MPM",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  claude-mpm agent-manager list                          # List all agents across tiers
+  claude-mpm agent-manager create                        # Interactive agent creation
+  claude-mpm agent-manager create --id my-agent          # Create agent with ID
+  claude-mpm agent-manager variant --base research       # Create research variant
+  claude-mpm agent-manager deploy --id my-agent --tier user  # Deploy to user tier
+  claude-mpm agent-manager customize-pm --level project  # Edit .claude-mpm/INSTRUCTIONS.md
+  claude-mpm agent-manager show --id engineer            # Show agent details
+  claude-mpm agent-manager test --id my-agent            # Test agent configuration
+  claude-mpm agent-manager templates                     # List available templates
+"""
+    )
+    
+    # Create subcommands for agent-manager
+    agent_subparsers = agent_manager_parser.add_subparsers(
+        dest="agent_manager_command",
+        help="Agent management operations",
+        metavar="OPERATION"
+    )
+    
+    # List command
+    list_parser = agent_subparsers.add_parser(
+        "list",
+        help="List all agents across tiers with hierarchy"
+    )
+    list_parser.add_argument(
+        "--format",
+        choices=["text", "json", "yaml"],
+        default="text",
+        help="Output format (default: text)"
+    )
+    
+    # Create command
+    create_parser = agent_subparsers.add_parser(
+        "create",
+        help="Create a new agent (interactive or with arguments)"
+    )
+    create_parser.add_argument(
+        "--id",
+        dest="agent_id",
+        help="Agent ID (lowercase, hyphens only)"
+    )
+    create_parser.add_argument(
+        "--name",
+        help="Display name for the agent"
+    )
+    create_parser.add_argument(
+        "--description",
+        help="Agent purpose and capabilities"
+    )
+    create_parser.add_argument(
+        "--model",
+        choices=["sonnet", "opus", "haiku"],
+        default="sonnet",
+        help="LLM model to use (default: sonnet)"
+    )
+    create_parser.add_argument(
+        "--tool-choice",
+        choices=["auto", "required", "any", "none"],
+        default="auto",
+        help="Tool selection strategy (default: auto)"
+    )
+    create_parser.add_argument(
+        "--template",
+        help="Base template to extend from"
+    )
+    create_parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text)"
+    )
+    
+    # Variant command
+    variant_parser = agent_subparsers.add_parser(
+        "variant",
+        help="Create an agent variant based on existing agent"
+    )
+    variant_parser.add_argument(
+        "--base",
+        dest="base_agent",
+        required=True,
+        help="Base agent ID to create variant from"
+    )
+    variant_parser.add_argument(
+        "--id",
+        dest="variant_id",
+        required=True,
+        help="Variant agent ID"
+    )
+    variant_parser.add_argument(
+        "--name",
+        help="Display name for the variant"
+    )
+    variant_parser.add_argument(
+        "--model",
+        choices=["sonnet", "opus", "haiku"],
+        help="Override model for variant"
+    )
+    variant_parser.add_argument(
+        "--tool-choice",
+        choices=["auto", "required", "any", "none"],
+        help="Override tool choice for variant"
+    )
+    variant_parser.add_argument(
+        "--instructions",
+        help="Additional instructions to append for variant"
+    )
+    variant_parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text)"
+    )
+    
+    # Deploy command
+    deploy_parser = agent_subparsers.add_parser(
+        "deploy",
+        help="Deploy agent to specified tier"
+    )
+    deploy_parser.add_argument(
+        "--id",
+        dest="agent_id",
+        required=True,
+        help="Agent ID to deploy"
+    )
+    deploy_parser.add_argument(
+        "--tier",
+        choices=["project", "user"],
+        default="user",
+        help="Deployment tier (default: user)"
+    )
+    deploy_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Force deployment even if agent exists"
+    )
+    deploy_parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text)"
+    )
+    
+    # Customize PM command
+    pm_parser = agent_subparsers.add_parser(
+        "customize-pm",
+        help="Customize PM instructions via .claude-mpm/INSTRUCTIONS.md"
+    )
+    pm_parser.add_argument(
+        "--level",
+        choices=["user", "project"],
+        default="user",
+        help="PM instruction level - user (~/.claude-mpm) or project (./.claude-mpm) (default: user)"
+    )
+    pm_parser.add_argument(
+        "--template",
+        help="Use predefined PM template"
+    )
+    pm_parser.add_argument(
+        "--patterns",
+        nargs="+",
+        help="Custom delegation patterns"
+    )
+    pm_parser.add_argument(
+        "--rules",
+        nargs="+",
+        help="Additional PM rules"
+    )
+    pm_parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text)"
+    )
+    
+    # Show command
+    show_parser = agent_subparsers.add_parser(
+        "show",
+        help="Display detailed agent information"
+    )
+    show_parser.add_argument(
+        "--id",
+        dest="agent_id",
+        required=True,
+        help="Agent ID to show"
+    )
+    show_parser.add_argument(
+        "--format",
+        choices=["text", "json", "yaml"],
+        default="text",
+        help="Output format (default: text)"
+    )
+    
+    # Test command
+    test_parser = agent_subparsers.add_parser(
+        "test",
+        help="Test and validate agent configuration"
+    )
+    test_parser.add_argument(
+        "--id",
+        dest="agent_id",
+        required=True,
+        help="Agent ID to test"
+    )
+    test_parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text)"
+    )
+    
+    # Templates command
+    templates_parser = agent_subparsers.add_parser(
+        "templates",
+        help="List available agent templates"
+    )
+    templates_parser.add_argument(
+        "--format",
+        choices=["text", "json", "yaml"],
+        default="text",
+        help="Output format (default: text)"
+    )