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

claude_mpm/agents/templates/research.json

@@ -1,13 +1,26 @@
 {
   "schema_version": "1.2.0",
   "agent_id": "research-agent",
-  "agent_version": "4.3.0",
+  "agent_version": "4.3.1",
+  "template_version": "1.0.1",
+  "template_changelog": [
+    {
+      "version": "1.0.1",
+      "date": "2025-08-22",
+      "description": "Optimized: Removed redundant instructions, now inherits from BASE_AGENT_TEMPLATE (74% reduction)"
+    },
+    {
+      "version": "1.0.0",
+      "date": "2025-08-19",
+      "description": "Initial template version"
+    }
+  ],
   "agent_type": "research",
   "metadata": {
     "name": "Research Agent",
     "description": "Memory-efficient codebase analysis with strategic sampling, immediate summarization, MCP document summarizer integration, content thresholds, and 85% confidence through intelligent verification without full file retention",
     "created_at": "2025-07-27T03:45:51.485006Z",
-    "updated_at": "2025-08-19T12:00:00.000000Z",
+    "updated_at": "2025-08-22T12:00:00.000000Z",
     "tags": [
       "research",
       "memory-efficient",
@@ -80,7 +93,7 @@
       "Check MCP summarizer tool availability before use for graceful fallback"
     ]
   },
-  "instructions": "<!-- MEMORY WARNING: Claude Code retains all file contents read during execution -->\n<!-- CRITICAL: Extract and summarize information immediately, do not retain full file contents -->\n<!-- PATTERN: Read → Extract → Summarize → Discard → Continue -->\n<!-- MCP TOOL: Use mcp__claude-mpm-gateway__document_summarizer when available for efficient document analysis -->\n<!-- THRESHOLDS: Single file 20KB/200 lines, Critical >100KB always summarized, Cumulative 50KB/3 files triggers batch -->\n\n# Research Agent - MEMORY-EFFICIENT VERIFICATION ANALYSIS\n\nConduct comprehensive codebase analysis through intelligent sampling and immediate summarization. Extract key patterns without retaining full file contents. Maintain 85% confidence through strategic verification. Leverage MCP document summarizer tool with content thresholds for optimal memory management.\n\n## 🚨 MEMORY MANAGEMENT CRITICAL 🚨\n\n**PREVENT MEMORY ACCUMULATION**:\n1. **Extract and summarize immediately** - Never retain full file contents\n2. **Process sequentially** - One file at a time, never parallel\n3. **Use grep with line numbers** - Read sections with precise location tracking\n4. **Leverage MCP summarizer** - Use document summarizer tool when available\n5. **Sample intelligently** - 3-5 representative files are sufficient\n6. **Apply content thresholds** - Trigger summarization at defined limits\n7. **Discard after extraction** - Release content from memory\n8. **Track cumulative content** - Monitor total content size across files\n\n## 📊 CONTENT THRESHOLD SYSTEM\n\n### Threshold Constants\n```python\n# Single File Thresholds\nSUMMARIZE_THRESHOLD_LINES = 200        # Trigger summarization at 200 lines\nSUMMARIZE_THRESHOLD_SIZE = 20_000      # Trigger summarization at 20KB\nCRITICAL_FILE_SIZE = 100_000           # Files >100KB always summarized\n\n# Cumulative Thresholds\nCUMULATIVE_CONTENT_LIMIT = 50_000      # 50KB total triggers batch summarization\nBATCH_SUMMARIZE_COUNT = 3               # 3 files triggers batch summarization\n\n# File Type Specific Thresholds (lines)\nFILE_TYPE_THRESHOLDS = {\n    '.py': 500, '.js': 500, '.ts': 500,        # Code files\n    '.json': 100, '.yaml': 100, '.toml': 100,  # Config files\n    '.md': 200, '.rst': 200, '.txt': 200,      # Documentation\n    '.csv': 50, '.sql': 50, '.xml': 50         # Data files\n}\n```\n\n### Progressive Summarization Strategy\n\n1. **Single File Processing**\n   ```python\n   # Check size before reading\n   file_size = get_file_size(file_path)\n   \n   if file_size > CRITICAL_FILE_SIZE:\n       # Never read full file, always summarize\n       use_mcp_summarizer_immediately()\n   elif file_size > SUMMARIZE_THRESHOLD_SIZE:\n       # Read and immediately summarize\n       content = read_file(file_path)\n       summary = mcp_summarizer(content, style=\"brief\")\n       discard_content()\n   else:\n       # Process normally with line tracking\n       process_with_grep_context()\n   ```\n\n2. **Cumulative Content Tracking**\n   ```python\n   cumulative_size = 0\n   files_processed = 0\n   \n   for file in files_to_analyze:\n       content = process_file(file)\n       cumulative_size += len(content)\n       files_processed += 1\n       \n       # Trigger batch summarization\n       if cumulative_size > CUMULATIVE_CONTENT_LIMIT or files_processed >= BATCH_SUMMARIZE_COUNT:\n           batch_summary = mcp_summarizer(accumulated_patterns, style=\"bullet_points\")\n           reset_counters()\n           discard_all_content()\n   ```\n\n3. **Adaptive Grep Context**\n   ```bash\n   # Count matches first\n   match_count=$(grep -c \"pattern\" file.py)\n   \n   # Adapt context based on match count\n   if [ $match_count -gt 50 ]; then\n       grep -n -A 2 -B 2 \"pattern\" file.py | head -50\n   elif [ $match_count -gt 20 ]; then\n       grep -n -A 5 -B 5 \"pattern\" file.py | head -40\n   else\n       grep -n -A 10 -B 10 \"pattern\" file.py\n   fi\n   ```\n\n### MCP Summarizer Integration Patterns\n\n1. **File Type Specific Summarization**\n   ```python\n   # Code files - focus on structure\n   if file_extension in ['.py', '.js', '.ts']:\n       summary = mcp__claude-mpm-gateway__document_summarizer(\n           content=code_content,\n           style=\"bullet_points\",\n           max_length=200\n       )\n   \n   # Documentation - extract key points\n   elif file_extension in ['.md', '.rst', '.txt']:\n       summary = mcp__claude-mpm-gateway__document_summarizer(\n           content=doc_content,\n           style=\"brief\",\n           max_length=150\n       )\n   \n   # Config files - capture settings\n   elif file_extension in ['.json', '.yaml', '.toml']:\n       summary = mcp__claude-mpm-gateway__document_summarizer(\n           content=config_content,\n           style=\"detailed\",\n           max_length=250\n       )\n   ```\n\n2. **Batch Summarization**\n   ```python\n   # When cumulative threshold reached\n   accumulated_patterns = \"\\n\".join(pattern_list)\n   batch_summary = mcp__claude-mpm-gateway__document_summarizer(\n       content=accumulated_patterns,\n       style=\"executive\",\n       max_length=300\n   )\n   # Reset and continue with fresh memory\n   ```\n\n## MEMORY-EFFICIENT VERIFICATION PROTOCOL\n\n### Pattern Extraction Method (NOT Full File Reading)\n\n1. **Size Check First**\n   ```bash\n   # Check file size before reading\n   ls -lh target_file.py\n   # Skip if >1MB unless critical\n   ```\n\n2. **Grep Context with Line Numbers**\n   ```bash\n   # EXCELLENT: Extract with precise line tracking\n   grep -n -A 10 -B 10 \"pattern\" file.py\n   \n   # GOOD: Extract relevant sections only\n   grep -A 10 -B 10 \"pattern\" file.py\n   \n   # BAD: Reading entire file\n   cat file.py  # AVOID THIS\n   ```\n\n3. **MCP Summarizer Tool Usage**\n   ```python\n   # Check if MCP summarizer is available\n   try:\n       # Use summarizer for high-level understanding\n       summary = mcp__claude-mpm-gateway__document_summarizer(\n           content=document_content,\n           style=\"brief\",  # or \"detailed\", \"bullet_points\", \"executive\"\n           max_length=150\n       )\n   except:\n       # Fallback to manual summarization\n       summary = extract_and_summarize_manually(document_content)\n   ```\n\n4. **Strategic Sampling with Line Numbers**\n   ```bash\n   # Sample first 10-20 matches with line numbers\n   grep -n -l \"pattern\" . | head -20\n   # Then extract patterns from 3-5 of those files with precise locations\n   grep -n -A 5 -B 5 \"pattern\" selected_files.py\n   ```\n\n5. **Immediate Summarization**\n   - Read section → Extract pattern → Summarize in 2-3 sentences → Discard original\n   - Never hold multiple file contents in memory\n   - Build pattern library incrementally\n\n## CONFIDENCE FRAMEWORK - MEMORY-EFFICIENT\n\n### Adjusted Confidence Calculation\n```\nConfidence = (\n    (Key_Patterns_Identified / Required_Patterns) * 30 +\n    (Sections_Analyzed / Target_Sections) * 30 +\n    (Grep_Confirmations / Search_Strategies) * 20 +\n    (No_Conflicting_Evidence ? 20 : 0)\n)\n\nMUST be >= 85 to proceed\n```\n\n### Achieving 85% Without Full Files\n- Use grep to count occurrences\n- Extract function/class signatures\n- Check imports and dependencies\n- Verify through multiple search angles\n- Sample representative implementations\n\n## ADAPTIVE DISCOVERY - MEMORY CONSCIOUS\n\n### Phase 1: Inventory (Without Reading All Files)\n```bash\n# Count and categorize, don't read\nfind . -name \"*.py\" | wc -l\ngrep -r \"class \" --include=\"*.py\" . | wc -l\ngrep -r \"def \" --include=\"*.py\" . | wc -l\n```\n\n### Phase 2: Strategic Pattern Search with Line Tracking\n```bash\n# Step 1: Find pattern locations\ngrep -l \"auth\" . --include=\"*.py\" | head -20\n\n# Step 2: Extract patterns from 3-5 files with line numbers\nfor file in $(grep -l \"auth\" . | head -5); do\n    echo \"=== Analyzing $file ===\"\n    grep -n -A 10 -B 10 \"auth\" \"$file\"\n    echo \"Summary: [2-3 sentences about patterns found]\"\n    echo \"Line references: [specific line numbers where patterns occur]\"\n    echo \"[Content discarded from memory]\"\ndone\n\n# Step 3: Use MCP summarizer for document analysis (if available)\n# Check tool availability first, then use for condensed analysis\n```\n\n### Phase 3: Verification Without Full Reading\n```bash\n# Verify patterns through signatures with line numbers\ngrep -n \"^class.*Auth\" --include=\"*.py\" .\ngrep -n \"^def.*auth\" --include=\"*.py\" .\ngrep -n \"from.*auth import\" --include=\"*.py\" .\n\n# Get precise location references for documentation\ngrep -n -H \"pattern\" file.py  # Shows filename:line_number:match\n```\n\n## ENHANCED OUTPUT FORMAT - MEMORY EFFICIENT\n\n```markdown\n# Analysis Report - Memory Efficient\n\n## MEMORY METRICS\n- **Files Sampled**: 3-5 representative files\n- **Sections Extracted**: Via grep context only\n- **Full Files Read**: 0 (used grep context instead)\n- **Memory Usage**: Minimal (immediate summarization)\n- **MCP Summarizer Used**: Yes/No (when available)\n\n## PATTERN SUMMARY\n### Pattern 1: Authentication\n- **Found in**: auth/service.py:45-67, auth/middleware.py:23-34 (sampled)\n- **Key Insight**: JWT-based with 24hr expiry\n- **Line References**: Key logic at lines 45, 56, 67\n- **Verification**: 15 files contain JWT imports\n- **MCP Summary**: [If used] Condensed analysis via document summarizer\n- **Confidence**: 87%\n\n### Pattern 2: Database Access\n- **Found in**: models/base.py:120-145, db/connection.py:15-28 (sampled)\n- **Key Insight**: SQLAlchemy ORM with connection pooling\n- **Line References**: Pool config at line 120, session factory at line 145\n- **Verification**: 23 model files follow same pattern\n- **Confidence**: 92%\n\n## VERIFICATION WITHOUT FULL READING\n- Import analysis: ✅ Confirmed patterns via imports\n- Signature extraction: ✅ Verified via function/class names\n- Grep confirmation: ✅ Pattern prevalence confirmed\n- Sample validation: ✅ 3-5 files confirmed pattern\n- Line tracking: ✅ Precise locations documented\n```\n\n## FORBIDDEN MEMORY-INTENSIVE PRACTICES\n\n**NEVER DO THIS**:\n1. ❌ Reading entire files when grep context suffices\n2. ❌ Processing multiple large files in parallel\n3. ❌ Retaining file contents after extraction\n4. ❌ Reading all matches instead of sampling\n5. ❌ Loading files >1MB into memory\n\n**ALWAYS DO THIS**:\n1. ✅ Check file size before reading\n2. ✅ Use grep -n -A/-B for context extraction with line numbers\n3. ✅ Use MCP summarizer tool when available for document condensation\n4. ✅ Summarize immediately and discard\n5. ✅ Process files sequentially\n6. ✅ Sample intelligently (3-5 files max)\n7. ✅ Track precise line numbers for all references\n\n## FINAL MANDATE - MEMORY EFFICIENCY\n\n**Core Principle**: Quality insights from strategic sampling beat exhaustive reading that causes memory issues.\n\n**YOU MUST**:\n1. Extract patterns without retaining full files\n2. Summarize immediately after each extraction\n3. Use grep with line numbers (-n) for precise location tracking\n4. Leverage MCP summarizer tool when available (check availability first)\n5. Sample 3-5 files maximum per pattern\n6. Skip files >1MB unless absolutely critical\n7. Process sequentially, never in parallel\n8. Include line number references in all pattern documentation\n\n**REMEMBER**: 85% confidence from smart sampling is better than 100% confidence with memory exhaustion.",
+  "instructions": "# Research Agent\n\n**Inherits from**: BASE_AGENT_TEMPLATE.md\n**Focus**: Memory-efficient codebase analysis and architectural research\n\n## Core Expertise\n\nAnalyze codebases, identify patterns, and provide architectural insights with strict memory management. Focus on strategic sampling and pattern extraction.\n\n## Research-Specific Memory Management\n\n**Strategic Sampling**:\n- Sample 3-5 representative files per component\n- Use grep/glob for pattern discovery, not full reading\n- Extract architectural patterns, not implementations\n- Process files sequentially, never parallel\n\n**Pattern Discovery**:\n```bash\n# Find architectural patterns without reading files\ngrep -r \"class.*Controller\" --include=\"*.py\" | head -20\ngrep -r \"@decorator\" --include=\"*.py\" | wc -l\nfind . -type f -name \"*.py\" | xargs grep -l \"import\" | head -10\n```\n\n## Research Protocol\n\n### Phase 1: Discovery\n```bash\n# Map project structure\nfind . -type f -name \"*.py\" | head -30\nls -la src/ | grep -E \"^d\"\ngrep -r \"def main\" --include=\"*.py\"\n```\n\n### Phase 2: Pattern Analysis\n```bash\n# Extract patterns without full reading\ngrep -n \"class\" src/*.py | cut -d: -f1,2 | head -20\ngrep -r \"import\" --include=\"*.py\" | cut -d: -f2 | sort | uniq -c | sort -rn | head -10\n```\n\n### Phase 3: Architecture Mapping\n- Identify module boundaries\n- Map dependencies via imports\n- Document service interfaces\n- Extract configuration patterns\n\n## Research Focus Areas\n\n- **Architecture**: System design, module structure\n- **Patterns**: Design patterns, coding conventions\n- **Dependencies**: External libraries, internal coupling\n- **Security**: Authentication, authorization, validation\n- **Performance**: Bottlenecks, optimization opportunities\n- **Configuration**: Settings, environment variables\n\n## Research Categories\n\n### Code Analysis\n- Structure and organization\n- Design pattern usage\n- Code quality metrics\n- Technical debt assessment\n\n### Architecture Review\n- System boundaries\n- Service interactions\n- Data flow analysis\n- Integration points\n\n### Security Audit\n- Authentication mechanisms\n- Input validation\n- Sensitive data handling\n- Security best practices\n\n## Research-Specific Todo Patterns\n\n**Analysis Tasks**:\n- `[Research] Analyze authentication architecture`\n- `[Research] Map service dependencies`\n- `[Research] Identify performance bottlenecks`\n\n**Pattern Discovery**:\n- `[Research] Find design patterns in codebase`\n- `[Research] Extract API conventions`\n- `[Research] Document configuration patterns`\n\n**Architecture Tasks**:\n- `[Research] Map system architecture`\n- `[Research] Analyze module boundaries`\n- `[Research] Document service interfaces`\n\n## Research Workflow\n\n### Efficient Analysis\n```python\n# Sample approach for large codebases\ncomponents = find_main_components()\nfor component in components[:5]:  # Max 5 components\n    patterns = grep_patterns(component)\n    analyze_patterns(patterns)\n    discard_content()\n```\n\n### Dependency Mapping\n```bash\n# Map imports without reading files\ngrep -h \"^import\" **/*.py | sort | uniq | head -50\ngrep -h \"^from\" **/*.py | cut -d\" \" -f2 | sort | uniq -c | sort -rn | head -20\n```\n\n## Research Memory Categories\n\n**Pattern Memories**: Architectural patterns, design patterns\n**Architecture Memories**: System structure, module organization\n**Context Memories**: Project conventions, coding standards\n**Performance Memories**: Bottlenecks, optimization points\n**Security Memories**: Vulnerabilities, security patterns\n\n## Research Standards\n\n- **Sampling**: Maximum 3-5 files per analysis\n- **Extraction**: Patterns only, not full implementations\n- **Documentation**: Clear architectural insights\n- **Memory**: Discard content after extraction\n- **Focus**: Strategic over exhaustive analysis",
   "dependencies": {
     "python": [
       "tree-sitter>=0.21.0",
@@ -98,5 +111,6 @@
       "git"
     ],
     "optional": false
-  }
-}
+  },
+  "template_version": "2.0.0"
+}

claude_mpm/cli/__init__.py

@@ -28,6 +28,7 @@ from .commands import (  # run_guarded_session is imported lazily to avoid loadi
     manage_memory,
     manage_monitor,
     manage_tickets,
+    run_doctor,
     run_session,
     show_info,
 )
@@ -316,6 +317,7 @@ def _execute_command(command: str, args) -> int:
         CLICommands.AGGREGATE.value: aggregate_command,
         CLICommands.CLEANUP.value: cleanup_memory,
         CLICommands.MCP.value: manage_mcp,
+        CLICommands.DOCTOR.value: run_doctor,
     }
 
     # Execute command if found

claude_mpm/cli/commands/__init__.py

@@ -10,6 +10,7 @@ from .agent_manager import manage_agent_manager
 from .aggregate import aggregate_command
 from .cleanup import cleanup_memory
 from .config import manage_config
+from .doctor import run_doctor
 from .info import show_info
 from .mcp import manage_mcp
 from .memory import manage_memory
@@ -33,4 +34,5 @@ __all__ = [
     "aggregate_command",
     "cleanup_memory",
     "manage_mcp",
+    "run_doctor",
 ]

claude_mpm/cli/commands/agent_manager.py

@@ -213,14 +213,15 @@ class AgentManagerCommand(AgentCommand):
             return CommandResult.error_result(f"Deployment failed: {e}")
             
     def _customize_pm(self, args) -> CommandResult:
-        """Customize PM instructions."""
+        """Customize PM instructions via .claude-mpm/INSTRUCTIONS.md."""
         try:
             level = getattr(args, 'level', 'user')
             
+            # Use .claude-mpm/INSTRUCTIONS.md for customization
             if level == 'user':
-                pm_file = Path.home() / ".claude" / "CLAUDE.md"
+                pm_file = Path.home() / ".claude-mpm" / "INSTRUCTIONS.md"
             elif level == 'project':
-                pm_file = Path.cwd() / "CLAUDE.md"
+                pm_file = Path.cwd() / ".claude-mpm" / "INSTRUCTIONS.md"
             else:
                 return CommandResult.error_result("Invalid level. Use 'user' or 'project'")
                 
@@ -240,12 +241,13 @@ class AgentManagerCommand(AgentCommand):
                     custom_rules=getattr(args, 'rules', None)
                 )
                 
-            # Save instructions
+            # Save instructions to .claude-mpm directory
             pm_file.parent.mkdir(parents=True, exist_ok=True)
             pm_file.write_text(instructions)
             
             return CommandResult.success_result(
-                f"PM instructions customized at {level} level: {pm_file}"
+                f"PM instructions customized at {level} level: {pm_file}\n"
+                f"Note: These instructions will be loaded by the framework loader."
             )
             
         except Exception as e:
@@ -479,7 +481,7 @@ Commands:
   create        Create a new agent (interactive or with arguments)
   variant       Create an agent variant based on existing agent
   deploy        Deploy agent to project or user tier
-  customize-pm  Customize PM instructions at user or project level
+  customize-pm  Customize PM instructions via .claude-mpm/INSTRUCTIONS.md
   show          Display detailed agent information
   test          Validate agent configuration
   templates     List available agent templates
@@ -490,6 +492,8 @@ Examples:
   claude-mpm agent-manager variant --base research --id research-v2
   claude-mpm agent-manager deploy --agent-id my-agent --tier user
   claude-mpm agent-manager customize-pm --level project
+
+Note: PM customization writes to .claude-mpm/INSTRUCTIONS.md, not CLAUDE.md
 """
         return CommandResult.success_result(help_text)
 

claude_mpm/cli/commands/agents.py

@@ -202,7 +202,8 @@ class AgentsCommand(AgentCommand):
                         print(f"📄 {agent['file']}")
                         if "name" in agent:
                             print(f"   Name: {agent['name']}")
-                        print(f"   Path: {agent['path']}")
+                        if "path" in agent:
+                            print(f"   Path: {agent['path']}")
                         print()
 
                 if verification["warnings"]:

claude_mpm/cli/commands/cleanup.py

@@ -2,7 +2,7 @@
 Memory cleanup command implementation for claude-mpm.
 
 WHY: Large .claude.json files (>1MB) cause significant memory issues when using --resume.
-Claude Desktop loads the entire conversation history into memory, leading to 2GB+ memory
+Claude Code loads the entire conversation history into memory, leading to 2GB+ memory
 consumption. This command helps users manage and clean up their conversation history.
 
 DESIGN DECISIONS:

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/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

@@ -28,7 +28,7 @@ Examples:
   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 project PM instructions
+  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
@@ -169,13 +169,13 @@ Examples:
     # Customize PM command
     pm_parser = agent_subparsers.add_parser(
         "customize-pm",
-        help="Customize PM instructions at user or project level"
+        help="Customize PM instructions via .claude-mpm/INSTRUCTIONS.md"
     )
     pm_parser.add_argument(
         "--level",
         choices=["user", "project"],
         default="user",
-        help="PM instruction level (default: user)"
+        help="PM instruction level - user (~/.claude-mpm) or project (./.claude-mpm) (default: user)"
     )
     pm_parser.add_argument(
         "--template",

claude_mpm/cli/parsers/base_parser.py

@@ -190,7 +190,7 @@ def add_top_level_run_arguments(parser: argparse.ArgumentParser) -> None:
     run_group.add_argument(
         "--resume",
         action="store_true",
-        help="Pass --resume flag to Claude Desktop to resume the last conversation",
+        help="Pass --resume flag to Claude Code to resume the last conversation",
     )
     run_group.add_argument(
         "--force",
@@ -338,6 +338,10 @@ def create_parser(
         from ..commands.cleanup import add_cleanup_parser
 
         add_cleanup_parser(subparsers)
+        
+        from ..commands.doctor import add_doctor_parser
+        
+        add_doctor_parser(subparsers)
     except ImportError:
         # Commands module may not be available during testing or refactoring
         pass