claude-mpm 5.4.85__py3-none-any.whl → 5.6.1__py3-none-any.whl

claude_mpm/cli/parsers/commander_parser.py

@@ -0,0 +1,83 @@
+"""
+Commander parser module for claude-mpm CLI.
+
+WHY: This module provides the commander subcommand for interactive instance management
+and chat interface.
+
+DESIGN DECISION: Uses subparser pattern consistent with other commands (run, agents, etc.)
+to provide a clean interface for Commander mode.
+"""
+
+import argparse
+from pathlib import Path
+
+
+def add_commander_subparser(subparsers: argparse._SubParsersAction) -> None:
+    """
+    Add commander subcommand parser.
+
+    WHY: Provides interactive mode for managing and chatting with multiple Claude instances.
+
+    Args:
+        subparsers: The subparsers object to add the commander parser to
+    """
+    commander_parser = subparsers.add_parser(
+        "commander",
+        help="Interactive Commander mode for managing multiple Claude instances",
+        description="""
+Commander Mode - Interactive Instance Management
+
+Commander provides an interactive REPL interface for:
+- Starting and stopping Claude Code/MPM instances in tmux
+- Connecting to instances and sending natural language commands
+- Managing multiple concurrent projects
+- Viewing instance status and output
+
+Commands:
+  list, ls, instances   List active instances
+  start <path>          Start new instance at path
+    --framework <cc|mpm>  Specify framework (default: cc)
+    --name <name>         Specify instance name (default: dir name)
+  stop <name>           Stop an instance
+  connect <name>        Connect to an instance
+  disconnect            Disconnect from current instance
+  status                Show current session status
+  help                  Show help message
+  exit, quit, q         Exit Commander
+
+Natural Language:
+  When connected to an instance, any input that is not a built-in
+  command will be sent to the connected instance as a message.
+
+Examples:
+  claude-mpm commander
+  > start ~/myproject --framework cc --name myapp
+  > connect myapp
+  > Fix the authentication bug in login.py
+  > disconnect
+  > exit
+        """,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    # Optional: Port for internal services
+    commander_parser.add_argument(
+        "--port",
+        type=int,
+        default=8765,
+        help="Port for internal services (default: 8765)",
+    )
+
+    # Optional: State directory
+    commander_parser.add_argument(
+        "--state-dir",
+        type=Path,
+        help="Directory for state persistence (optional)",
+    )
+
+    # Debug mode
+    commander_parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Enable debug logging",
+    )

claude_mpm/cli/parsers/run_parser.py

@@ -85,6 +85,16 @@ def add_run_arguments(parser: argparse.ArgumentParser) -> None:
         action="store_true",
         help="Pass --resume flag to Claude Code to resume the last conversation",
     )
+    run_group.add_argument(
+        "--chrome",
+        action="store_true",
+        help="Enable Claude in Chrome integration (passed to Claude Code)",
+    )
+    run_group.add_argument(
+        "--no-chrome",
+        action="store_true",
+        help="Disable Claude in Chrome integration (passed to Claude Code)",
+    )
 
     # Dependency checking options
     dep_group = parser.add_argument_group("dependency options")

claude_mpm/cli/startup.py

@@ -191,7 +191,8 @@ def should_skip_background_services(args, processed_argv):
     skip_commands = ["--version", "-v", "--help", "-h"]
     return any(cmd in (processed_argv or sys.argv[1:]) for cmd in skip_commands) or (
         hasattr(args, "command")
-        and args.command in ["info", "doctor", "config", "mcp", "configure"]
+        and args.command
+        in ["info", "doctor", "config", "mcp", "configure", "hook-errors", "autotodos"]
     )
 
 
@@ -315,7 +316,7 @@ def deploy_output_style_on_startup():
     Deploys all styles:
     - claude-mpm.md (professional mode)
     - claude-mpm-teacher.md (teaching mode)
-    - claude-mpm-founders.md (founders mode)
+    - claude-mpm-research.md (research mode - for codebase analysis)
     """
     try:
         from ..core.output_style_manager import OutputStyleManager
@@ -1139,33 +1140,70 @@ def show_skill_summary():
 
 
 def verify_and_show_pm_skills():
-    """Verify PM skills and display status.
+    """Verify PM skills and display status with enhanced validation.
 
-    WHY: PM skills are essential for PM agent operation.
-    Shows deployment status and auto-deploys if missing.
+    WHY: PM skills are CRITICAL for PM agent operation. PM must KNOW if
+    framework knowledge is unavailable at startup. Enhanced validation
+    checks all required skills exist, are not corrupted, and auto-repairs
+    if needed.
+
+    Shows deployment status:
+    - "✓ PM skills: 8/8 verified" if all required skills are valid
+    - "⚠ PM skills: 2 missing, auto-repairing..." if issues detected
+    - Non-blocking but visible warning if auto-repair fails
     """
     try:
         from pathlib import Path
 
-        from ..services.pm_skills_deployer import PMSkillsDeployerService
+        from ..services.pm_skills_deployer import (
+            REQUIRED_PM_SKILLS,
+            PMSkillsDeployerService,
+        )
 
         deployer = PMSkillsDeployerService()
         project_dir = Path.cwd()
 
-        result = deployer.verify_pm_skills(project_dir)
+        # Verify with auto-repair enabled
+        result = deployer.verify_pm_skills(project_dir, auto_repair=True)
 
         if result.verified:
-            # Show verified status
-            print(f"✓ PM skills: {result.skill_count} verified", flush=True)
+            # Show verified status with count
+            total_required = len(REQUIRED_PM_SKILLS)
+            print(
+                f"✓ PM skills: {total_required}/{total_required} verified", flush=True
+            )
         else:
-            # Auto-deploy if missing
-            print("Deploying PM skills...", end="", flush=True)
-            deploy_result = deployer.deploy_pm_skills(project_dir)
-            if deploy_result.success:
-                total = len(deploy_result.deployed) + len(deploy_result.skipped)
-                print(f"\r✓ PM skills: {total} deployed" + " " * 20, flush=True)
+            # Show warning with details
+            missing_count = len(result.missing_skills)
+            corrupted_count = len(result.corrupted_skills)
+
+            # Build status message
+            issues = []
+            if missing_count > 0:
+                issues.append(f"{missing_count} missing")
+            if corrupted_count > 0:
+                issues.append(f"{corrupted_count} corrupted")
+
+            status = ", ".join(issues)
+
+            # Check if auto-repair was attempted
+            if "Auto-repaired" in result.message:
+                # Auto-repair succeeded
+                total_required = len(REQUIRED_PM_SKILLS)
+                print(
+                    f"✓ PM skills: {total_required}/{total_required} verified (auto-repaired)",
+                    flush=True,
+                )
             else:
-                print("\r⚠ PM skills: deployment failed" + " " * 20, flush=True)
+                # Auto-repair failed or not attempted
+                print(f"⚠ PM skills: {status}", flush=True)
+
+                # Log warnings for debugging
+                from ..core.logger import get_logger
+
+                logger = get_logger("cli")
+                for warning in result.warnings:
+                    logger.warning(f"PM skills: {warning}")
 
     except ImportError:
         # PM skills deployer not available - skip silently

claude_mpm/cli/startup_display.py

@@ -7,7 +7,7 @@ Shows welcome message, version info, ASCII art, and what's new section.
 import os
 import re
 import shutil
-import subprocess
+import subprocess  # nosec B404 - required for git operations
 from pathlib import Path
 from typing import List
 
@@ -65,8 +65,8 @@ def _get_recent_commits(max_commits: int = 3) -> List[str]:
         if not is_git_repository("."):
             return []
 
-        # Run git log with custom format
-        result = subprocess.run(
+        # Run git log with custom format (safe - no user input)
+        result = subprocess.run(  # nosec B603 B607
             ["git", "log", "--format=%h • %ar • %s", f"-{max_commits}"],
             capture_output=True,
             text=True,
@@ -216,6 +216,59 @@ def _get_cwd_display(max_width: int = 40) -> str:
     return "..." + cwd[-(max_width - 3) :]
 
 
+def _count_mpm_skills() -> int:
+    """
+    Count user-level MPM skills from ~/.claude/skills/.
+
+    Returns:
+        Number of skill directories with SKILL.md files
+    """
+    try:
+        user_skills_dir = Path.home() / ".claude" / "skills"
+        if not user_skills_dir.exists():
+            return 0
+
+        # Count directories with SKILL.md (skill directories)
+        skill_count = 0
+        for item in user_skills_dir.iterdir():
+            if item.is_dir():
+                skill_file = item / "SKILL.md"
+                if skill_file.exists():
+                    skill_count += 1
+            # Also count standalone .md files (legacy format)
+            elif item.is_file() and item.suffix == ".md" and item.name != "README.md":
+                skill_count += 1
+
+        return skill_count
+    except Exception:
+        # Silent failure - return 0 if any error
+        return 0
+
+
+def _count_deployed_agents() -> int:
+    """
+    Count deployed agents from .claude/agents/.
+
+    Returns:
+        Number of deployed agent files
+    """
+    try:
+        deploy_target = Path.cwd() / ".claude" / "agents"
+        if not deploy_target.exists():
+            return 0
+
+        # Count .md files, excluding README and other docs
+        agent_files = [
+            f
+            for f in deploy_target.glob("*.md")
+            if not f.name.startswith(("README", "INSTRUCTIONS", "."))
+        ]
+        return len(agent_files)
+    except Exception:
+        # Silent failure - return 0 if any error
+        return 0
+
+
 def _format_two_column_line(
     left: str, right: str, left_panel_width: int, right_panel_width: int
 ) -> str:
@@ -402,11 +455,25 @@ def display_startup_banner(version: str, logging_level: str) -> None:
             )
         )
 
-    # Line 10: Model info | separator
+    # Line 10: Model info with counts | separator
     separator = "─" * right_panel_width
+    agent_count = _count_deployed_agents()
+    skill_count = _count_mpm_skills()
+
+    # Format: "Sonnet 4.5 · 44 agents, 19 skills"
+    if agent_count > 0 or skill_count > 0:
+        counts_text = []
+        if agent_count > 0:
+            counts_text.append(f"{agent_count} agent{'s' if agent_count != 1 else ''}")
+        if skill_count > 0:
+            counts_text.append(f"{skill_count} skill{'s' if skill_count != 1 else ''}")
+        model_info = f"Sonnet 4.5 · {', '.join(counts_text)}"
+    else:
+        model_info = "Sonnet 4.5 · Claude MPM"
+
     lines.append(
         _format_two_column_line(
-            "Sonnet 4.5 · Claude MPM", separator, left_panel_width, right_panel_width
+            model_info, separator, left_panel_width, right_panel_width
         )
     )
 

claude_mpm/cli/startup_logging.py

@@ -672,7 +672,7 @@ async def trigger_vector_search_indexing(project_root: Optional[Path] = None) ->
             # Using installed binary
             cmd = [vector_search_path, "index", str(project_root)]
 
-        logger.info(
+        logger.debug(
             "MCP Vector Search: Starting background indexing for improved code search"
         )
 
@@ -761,7 +761,7 @@ def _start_vector_search_subprocess(project_root: Optional[Path] = None) -> None
         else:
             cmd = [vector_search_path, "index", str(project_root)]
 
-        logger.info(
+        logger.debug(
             "MCP Vector Search: Starting background indexing for improved code search"
         )
 

claude_mpm/cli/utils.py

@@ -107,7 +107,7 @@ def get_agent_versions_display() -> Optional[str]:
                     base_version_tuple
                 )
                 output_lines.append(f"\n  Base Agent Version:  {base_version_str}")
-        except Exception:
+        except Exception:  # nosec B110 - intentional: version display is optional
             pass
 
         # Check for agents needing migration
@@ -173,8 +173,12 @@ def setup_logging(args) -> object:
     if not hasattr(args, "logging") or args.logging is None:
         args.logging = LogLevel.OFF.value
 
+    # Handle deprecated --verbose flag
+    if hasattr(args, "verbose") and args.verbose and args.logging == LogLevel.OFF.value:
+        args.logging = LogLevel.INFO.value
+
     # Handle deprecated --debug flag
-    if hasattr(args, "debug") and args.debug and args.logging == LogLevel.INFO.value:
+    if hasattr(args, "debug") and args.debug:
         args.logging = LogLevel.DEBUG.value
 
     # Only setup logging if not OFF
@@ -204,7 +208,7 @@ def ensure_directories() -> None:
         from ..init import ensure_directories as init_ensure_directories
 
         init_ensure_directories()
-    except Exception:
+    except Exception:  # nosec B110
         # Continue even if initialization fails
         # The individual commands will handle missing directories as needed
         pass

claude_mpm/commander/__init__.py

@@ -0,0 +1,72 @@
+"""MPM Commander - Multi-Project Orchestration.
+
+This module provides the core infrastructure for managing multiple projects
+with isolated state, work queues, and tool sessions.
+
+Key Components:
+    - ProjectRegistry: Thread-safe project management
+    - Project models: Data structures for state and sessions
+    - TmuxOrchestrator: Tmux session and pane management
+    - Config loading: .claude-mpm/ directory configuration
+    - CommanderDaemon: Main daemon process for orchestration
+    - ProjectSession: Per-project lifecycle management
+    - InstanceManager: Framework selection and instance lifecycle
+    - Frameworks: Claude Code, MPM framework abstractions
+
+Example:
+    >>> from claude_mpm.commander import ProjectRegistry
+    >>> registry = ProjectRegistry()
+    >>> project = registry.register("/path/to/project")
+    >>> registry.update_state(project.id, ProjectState.WORKING)
+"""
+
+from claude_mpm.commander.config import DaemonConfig
+from claude_mpm.commander.config_loader import load_project_config
+from claude_mpm.commander.daemon import CommanderDaemon
+from claude_mpm.commander.frameworks import (
+    BaseFramework,
+    ClaudeCodeFramework,
+    InstanceInfo,
+    MPMFramework,
+)
+from claude_mpm.commander.instance_manager import (
+    FrameworkNotFoundError,
+    InstanceAlreadyExistsError,
+    InstanceManager,
+    InstanceNotFoundError,
+)
+from claude_mpm.commander.models import (
+    Project,
+    ProjectState,
+    ThreadMessage,
+    ToolSession,
+)
+from claude_mpm.commander.project_session import ProjectSession, SessionState
+from claude_mpm.commander.registry import ProjectRegistry
+from claude_mpm.commander.tmux_orchestrator import (
+    TmuxNotFoundError,
+    TmuxOrchestrator,
+)
+
+__all__ = [
+    "BaseFramework",
+    "ClaudeCodeFramework",
+    "CommanderDaemon",
+    "DaemonConfig",
+    "FrameworkNotFoundError",
+    "InstanceAlreadyExistsError",
+    "InstanceInfo",
+    "InstanceManager",
+    "InstanceNotFoundError",
+    "MPMFramework",
+    "Project",
+    "ProjectRegistry",
+    "ProjectSession",
+    "ProjectState",
+    "SessionState",
+    "ThreadMessage",
+    "TmuxNotFoundError",
+    "TmuxOrchestrator",
+    "ToolSession",
+    "load_project_config",
+]

claude_mpm/commander/adapters/__init__.py

@@ -0,0 +1,31 @@
+"""Runtime adapters for MPM Commander.
+
+This package provides adapters for different AI coding tools, allowing
+the TmuxOrchestrator to interface with various runtimes in a uniform way.
+
+Two types of adapters:
+- RuntimeAdapter: Synchronous parsing and state detection
+- CommunicationAdapter: Async I/O and state management
+"""
+
+from .base import Capability, ParsedResponse, RuntimeAdapter
+from .claude_code import ClaudeCodeAdapter
+from .communication import (
+    AdapterResponse,
+    AdapterState,
+    BaseCommunicationAdapter,
+    ClaudeCodeCommunicationAdapter,
+)
+
+__all__ = [
+    # Communication adapters (async I/O)
+    "AdapterResponse",
+    "AdapterState",
+    "BaseCommunicationAdapter",
+    # Runtime adapters (parsing)
+    "Capability",
+    "ClaudeCodeAdapter",
+    "ClaudeCodeCommunicationAdapter",
+    "ParsedResponse",
+    "RuntimeAdapter",
+]

claude_mpm/commander/adapters/base.py

@@ -0,0 +1,191 @@
+"""Base runtime adapter interface for MPM Commander.
+
+This module defines the abstract interface for runtime adapters that bridge
+between the TmuxOrchestrator and various AI coding tools (Claude Code, Cursor, etc.).
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from typing import List, Optional, Set
+
+
+class Capability(Enum):
+    """Capabilities that a runtime adapter can provide."""
+
+    TOOL_USE = "tool_use"
+    FILE_EDIT = "file_edit"
+    FILE_CREATE = "file_create"
+    GIT_OPERATIONS = "git_operations"
+    SHELL_COMMANDS = "shell_commands"
+    WEB_SEARCH = "web_search"
+    COMPLEX_REASONING = "complex_reasoning"
+
+
+@dataclass
+class ParsedResponse:
+    """Parsed output from a runtime tool.
+
+    Attributes:
+        content: The extracted text content, with ANSI codes removed
+        is_complete: True if tool is waiting for input (idle state)
+        is_error: True if an error was detected in the output
+        error_message: The error message if is_error is True
+        is_question: True if tool is asking a question
+        question_text: The question text if is_question is True
+        options: List of options if presenting a choice
+
+    Example:
+        >>> response = ParsedResponse(
+        ...     content="File created successfully",
+        ...     is_complete=True,
+        ...     is_error=False,
+        ...     error_message=None,
+        ...     is_question=False,
+        ...     question_text=None,
+        ...     options=None
+        ... )
+    """
+
+    content: str
+    is_complete: bool
+    is_error: bool
+    error_message: Optional[str] = None
+    is_question: bool = False
+    question_text: Optional[str] = None
+    options: Optional[List[str]] = None
+
+
+class RuntimeAdapter(ABC):
+    """Abstract base class for runtime adapters.
+
+    A runtime adapter provides the interface between the TmuxOrchestrator
+    and a specific AI coding tool. It handles:
+    - Launching the tool with appropriate settings
+    - Formatting input messages
+    - Detecting tool states (idle, error, questioning)
+    - Parsing tool output into structured responses
+
+    Example:
+        >>> class MyAdapter(RuntimeAdapter):
+        ...     @property
+        ...     def name(self) -> str:
+        ...         return "my-tool"
+        ...
+        ...     def build_launch_command(self, project_path: str) -> str:
+        ...         return f"cd {project_path} && my-tool --interactive"
+    """
+
+    @abstractmethod
+    def build_launch_command(
+        self, project_path: str, agent_prompt: Optional[str] = None
+    ) -> str:
+        """Generate shell command to start the tool.
+
+        Args:
+            project_path: Absolute path to the project directory
+            agent_prompt: Optional system prompt to configure the agent
+
+        Returns:
+            Shell command string ready to execute
+
+        Example:
+            >>> adapter.build_launch_command("/home/user/project", "You are a Python expert")
+            'cd /home/user/project && claude --system-prompt "You are a Python expert"'
+        """
+
+    @abstractmethod
+    def format_input(self, message: str) -> str:
+        """Prepare message for tool's input format.
+
+        Args:
+            message: The user message to send
+
+        Returns:
+            Formatted message ready to send to the tool
+
+        Example:
+            >>> adapter.format_input("Fix the bug in main.py")
+            'Fix the bug in main.py'
+        """
+
+    @abstractmethod
+    def detect_idle(self, output: str) -> bool:
+        """Recognize when tool is waiting for input.
+
+        Args:
+            output: Raw output from the tool (may contain ANSI codes)
+
+        Returns:
+            True if the tool is in an idle state awaiting input
+
+        Example:
+            >>> adapter.detect_idle("Done editing file.\\n> ")
+            True
+            >>> adapter.detect_idle("Processing request...")
+            False
+        """
+
+    @abstractmethod
+    def detect_error(self, output: str) -> Optional[str]:
+        """Recognize error states, return error message if found.
+
+        Args:
+            output: Raw output from the tool
+
+        Returns:
+            Error message string if error detected, None otherwise
+
+        Example:
+            >>> adapter.detect_error("Error: File not found: config.py")
+            'Error: File not found: config.py'
+            >>> adapter.detect_error("File edited successfully")
+            None
+        """
+
+    @abstractmethod
+    def parse_response(self, output: str) -> ParsedResponse:
+        """Extract meaningful content from output.
+
+        This method combines all detection logic (idle, error, questions)
+        into a single structured response.
+
+        Args:
+            output: Raw output from the tool
+
+        Returns:
+            ParsedResponse with all detected states and content
+
+        Example:
+            >>> response = adapter.parse_response("Error: Invalid input\\n> ")
+            >>> response.is_error
+            True
+            >>> response.is_complete
+            True
+        """
+
+    @property
+    @abstractmethod
+    def capabilities(self) -> Set[Capability]:
+        """What this tool can do.
+
+        Returns:
+            Set of Capability enums indicating supported features
+
+        Example:
+            >>> adapter.capabilities
+            {Capability.FILE_EDIT, Capability.TOOL_USE}
+        """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Runtime identifier.
+
+        Returns:
+            Unique name for this runtime adapter
+
+        Example:
+            >>> adapter.name
+            'claude-code'
+        """