claude-mpm 3.1.0__tar.gz → 3.1.2__tar.gz

{claude_mpm-3.1.0 → claude_mpm-3.1.2}/CLAUDE.md

@@ -52,6 +52,11 @@ See [docs/QA.md](docs/QA.md) for detailed testing procedures.
    - Business logic layer
    - Hook service, agent management, etc.
 
+4. **CLI System** (`src/claude_mpm/cli/`)
+   - Modular command structure
+   - Centralized argument parsing
+   - See [CLI Architecture](src/claude_mpm/cli/README.md) for details
+
 ## Quick Start
 
 ```bash

{claude_mpm-3.1.0/src/claude_mpm.egg-info → claude_mpm-3.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 3.1.0
+Version: 3.1.2
 Summary: Claude Multi-agent Project Manager - Clean orchestration with ticket management
 Home-page: https://github.com/bobmatnyc/claude-mpm
 Author: Claude MPM Team

{claude_mpm-3.1.0 → claude_mpm-3.1.2}/scripts/run_mpm.py

@@ -4,17 +4,13 @@
 import sys
 import os
 from pathlib import Path
-import importlib.util
 
 # Add src directory to Python path
 src_dir = Path(__file__).parent.parent / "src"
 sys.path.insert(0, str(src_dir))
 
-# Import from cli.py directly to avoid package/module confusion
-cli_path = src_dir / "claude_mpm" / "cli.py"
-spec = importlib.util.spec_from_file_location("cli_module", cli_path)
-cli_module = importlib.util.module_from_spec(spec)
-spec.loader.exec_module(cli_module)
+# Import from the new CLI module structure
+from claude_mpm.cli import main
 
 if __name__ == "__main__":
     # Enable debug logging if requested
@@ -22,4 +18,4 @@ if __name__ == "__main__":
         os.environ["CLAUDE_MPM_DEBUG"] = "1"
     
     # Run the CLI
-    sys.exit(cli_module.main())
+    sys.exit(main())

claude_mpm-3.1.2/src/claude_mpm/__main__.py

@@ -0,0 +1,21 @@
+"""
+Main entry point for claude-mpm package.
+
+WHY: This module enables running claude-mpm as a Python module via `python -m claude_mpm`.
+It's the standard Python pattern for making packages executable.
+
+DESIGN DECISION: We only import and call the main function from the CLI module,
+keeping this file minimal and focused on its single responsibility.
+"""
+
+import sys
+from pathlib import Path
+
+# Add parent directory to path to ensure proper imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+# Import main function from the new CLI module structure
+from claude_mpm.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

claude_mpm-3.1.2/src/claude_mpm/agents/templates/test-integration-agent.md

@@ -0,0 +1,34 @@
+---
+author: test-script
+model_preference: claude-3-sonnet
+specializations: []
+tags:
+- test
+- integration
+type: custom
+version: 1.0.0
+---
+
+# Test Integration Agent
+
+## 🎯 Primary Role
+test-integration-agent agent
+
+## 🎯 When to Use This Agent
+
+**Select this agent when:**
+
+**Do NOT select for:**
+
+## 🔧 Core Capabilities
+
+## 🔑 Authority & Permissions
+
+### ✅ Exclusive Write Access
+
+### ❌ Forbidden Operations
+
+---
+**Agent Type**: custom
+**Model Preference**: claude-3-sonnet
+**Version**: 1.0.0

claude_mpm-3.1.2/src/claude_mpm/cli/__init__.py

@@ -0,0 +1,163 @@
+"""
+Claude MPM Command-Line Interface.
+
+WHY: This module serves as the main entry point for the CLI, coordinating
+argument parsing and command execution. It replaces the monolithic cli.py
+with a more modular structure.
+
+DESIGN DECISION: We maintain backward compatibility by keeping the same
+interface while organizing code into logical modules. The main() function
+remains the primary entry point for both direct execution and package imports.
+"""
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+from ..constants import CLICommands, LogLevel
+from .parser import create_parser, preprocess_args
+from .utils import ensure_directories, setup_logging
+from .commands import (
+    run_session,
+    list_tickets,
+    show_info,
+    manage_agents,
+    run_terminal_ui
+)
+
+# Get version from VERSION file - single source of truth
+version_file = Path(__file__).parent.parent.parent / "VERSION"
+if version_file.exists():
+    __version__ = version_file.read_text().strip()
+else:
+    # Try to import from package as fallback
+    try:
+        from .. import __version__
+    except ImportError:
+        # Default version if all else fails
+        __version__ = "0.0.0"
+
+
+def main(argv: Optional[list] = None):
+    """
+    Main CLI entry point.
+    
+    WHY: This function orchestrates the entire CLI flow:
+    1. Ensures directories exist
+    2. Preprocesses arguments (handling --mpm: prefix)
+    3. Parses arguments
+    4. Sets up logging
+    5. Executes the appropriate command
+    
+    DESIGN DECISION: We keep error handling at this level to provide consistent
+    error messages and exit codes across all commands.
+    
+    Args:
+        argv: Optional list of command line arguments for testing
+        
+    Returns:
+        Exit code (0 for success, non-zero for errors)
+    """
+    # Ensure directories are initialized on first run
+    ensure_directories()
+    
+    # Create parser with version
+    parser = create_parser(version=__version__)
+    
+    # Preprocess and parse arguments
+    processed_argv = preprocess_args(argv)
+    args = parser.parse_args(processed_argv)
+    
+    # Set up logging
+    logger = setup_logging(args)
+    
+    # Debug output if requested
+    if hasattr(args, 'debug') and args.debug:
+        logger.debug(f"Command: {args.command}")
+        logger.debug(f"Arguments: {args}")
+    
+    # Hook system note: Claude Code hooks are handled externally via the
+    # hook_handler.py script installed in ~/.claude/settings.json
+    # The --no-hooks flag is kept for backward compatibility but doesn't affect
+    # Claude Code hooks which are configured separately.
+    
+    # Default to run command if no command specified
+    if not args.command:
+        args.command = CLICommands.RUN.value
+        # Ensure run-specific attributes exist when defaulting to run
+        _ensure_run_attributes(args)
+    
+    # Execute command
+    try:
+        exit_code = _execute_command(args.command, args)
+        return exit_code
+    except KeyboardInterrupt:
+        logger.info("Session interrupted by user")
+        return 0
+    except Exception as e:
+        logger.error(f"Error: {e}")
+        if args.debug:
+            import traceback
+            traceback.print_exc()
+        return 1
+
+
+def _ensure_run_attributes(args):
+    """
+    Ensure run command attributes exist when defaulting to run.
+    
+    WHY: When no command is specified, we default to 'run' but the args object
+    won't have run-specific attributes from the subparser. This function ensures
+    they exist with sensible defaults.
+    
+    Args:
+        args: Parsed arguments object to update
+    """
+    # Set defaults for run command attributes
+    args.no_tickets = getattr(args, 'no_tickets', False)
+    args.no_hooks = getattr(args, 'no_hooks', False)
+    args.intercept_commands = getattr(args, 'intercept_commands', False)
+    args.input = getattr(args, 'input', None)
+    args.non_interactive = getattr(args, 'non_interactive', False)
+    args.no_native_agents = getattr(args, 'no_native_agents', False)
+    args.claude_args = getattr(args, 'claude_args', [])
+
+
+def _execute_command(command: str, args) -> int:
+    """
+    Execute the specified command.
+    
+    WHY: This function maps command names to their implementations, providing
+    a single place to manage command routing.
+    
+    Args:
+        command: The command name to execute
+        args: Parsed command line arguments
+        
+    Returns:
+        Exit code from the command
+    """
+    # Map commands to their implementations
+    command_map = {
+        CLICommands.RUN.value: run_session,
+        CLICommands.TICKETS.value: list_tickets,
+        CLICommands.INFO.value: show_info,
+        CLICommands.AGENTS.value: manage_agents,
+        CLICommands.UI.value: run_terminal_ui,
+    }
+    
+    # Execute command if found
+    if command in command_map:
+        result = command_map[command](args)
+        # Commands may return None (success) or an exit code
+        return result if result is not None else 0
+    else:
+        # Unknown command - this shouldn't happen with argparse
+        # but we handle it for completeness
+        print(f"Unknown command: {command}")
+        return 1
+
+
+# For backward compatibility - export main
+if __name__ == "__main__":
+    sys.exit(main())

claude_mpm-3.1.2/src/claude_mpm/cli/commands/__init__.py

@@ -0,0 +1,20 @@
+"""
+CLI commands for claude-mpm.
+
+WHY: This package contains individual command implementations, organized into
+separate modules for better maintainability and code organization.
+"""
+
+from .run import run_session
+from .tickets import list_tickets
+from .info import show_info
+from .agents import manage_agents
+from .ui import run_terminal_ui
+
+__all__ = [
+    'run_session',
+    'list_tickets',
+    'show_info',
+    'manage_agents',
+    'run_terminal_ui'
+]

claude_mpm-3.1.2/src/claude_mpm/cli/commands/agents.py

@@ -0,0 +1,191 @@
+"""
+Agents command implementation for claude-mpm.
+
+WHY: This module manages Claude Code native agents, including listing, deploying,
+and cleaning agent deployments.
+"""
+
+from pathlib import Path
+
+from ...core.logger import get_logger
+from ...constants import AgentCommands
+from ..utils import get_agent_versions_display
+
+
+def manage_agents(args):
+    """
+    Manage Claude Code native agents.
+    
+    WHY: Claude Code agents need to be deployed and managed. This command provides
+    a unified interface for all agent-related operations.
+    
+    DESIGN DECISION: When no subcommand is provided, we show the current agent
+    versions as a quick status check. This matches the behavior users see at startup.
+    
+    Args:
+        args: Parsed command line arguments with agents_command attribute
+    """
+    logger = get_logger("cli")
+    
+    try:
+        from ...services.agent_deployment import AgentDeploymentService
+        deployment_service = AgentDeploymentService()
+        
+        if not args.agents_command:
+            # No subcommand - show agent versions
+            # WHY: This provides a quick way for users to check deployed agent versions
+            # without needing to specify additional subcommands
+            agent_versions = get_agent_versions_display()
+            if agent_versions:
+                print(agent_versions)
+            else:
+                print("No deployed agents found")
+                print("\nTo deploy agents, run: claude-mpm --mpm:agents deploy")
+            return
+        
+        if args.agents_command == AgentCommands.LIST.value:
+            _list_agents(args, deployment_service)
+        
+        elif args.agents_command == AgentCommands.DEPLOY.value:
+            _deploy_agents(args, deployment_service, force=False)
+        
+        elif args.agents_command == AgentCommands.FORCE_DEPLOY.value:
+            _deploy_agents(args, deployment_service, force=True)
+        
+        elif args.agents_command == AgentCommands.CLEAN.value:
+            _clean_agents(args, deployment_service)
+        
+    except ImportError:
+        logger.error("Agent deployment service not available")
+        print("Error: Agent deployment service not available")
+    except Exception as e:
+        logger.error(f"Error managing agents: {e}")
+        print(f"Error: {e}")
+
+
+def _list_agents(args, deployment_service):
+    """
+    List available or deployed agents.
+    
+    WHY: Users need to see what agents are available in the system and what's
+    currently deployed. This helps them understand the agent ecosystem.
+    
+    Args:
+        args: Command arguments with 'system' and 'deployed' flags
+        deployment_service: Agent deployment service instance
+    """
+    if args.system:
+        # List available agent templates
+        print("Available Agent Templates:")
+        print("-" * 80)
+        agents = deployment_service.list_available_agents()
+        if not agents:
+            print("No agent templates found")
+        else:
+            for agent in agents:
+                print(f"📄 {agent['file']}")
+                if 'name' in agent:
+                    print(f"   Name: {agent['name']}")
+                if 'description' in agent:
+                    print(f"   Description: {agent['description']}")
+                if 'version' in agent:
+                    print(f"   Version: {agent['version']}")
+                print()
+    
+    elif args.deployed:
+        # List deployed agents
+        print("Deployed Agents:")
+        print("-" * 80)
+        verification = deployment_service.verify_deployment()
+        if not verification["agents_found"]:
+            print("No deployed agents found")
+        else:
+            for agent in verification["agents_found"]:
+                print(f"📄 {agent['file']}")
+                if 'name' in agent:
+                    print(f"   Name: {agent['name']}")
+                print(f"   Path: {agent['path']}")
+                print()
+        
+        if verification["warnings"]:
+            print("\nWarnings:")
+            for warning in verification["warnings"]:
+                print(f"  ⚠️  {warning}")
+    
+    else:
+        # Default: show usage
+        print("Use --system to list system agents or --deployed to list deployed agents")
+
+
+def _deploy_agents(args, deployment_service, force=False):
+    """
+    Deploy system agents.
+    
+    WHY: Agents need to be deployed to the working directory for Claude Code to use them.
+    This function handles both regular and forced deployment.
+    
+    Args:
+        args: Command arguments with optional 'target' path
+        deployment_service: Agent deployment service instance
+        force: Whether to force rebuild all agents
+    """
+    if force:
+        print("Force deploying all system agents...")
+    else:
+        print("Deploying system agents...")
+    
+    results = deployment_service.deploy_agents(args.target, force_rebuild=force)
+    
+    if results["deployed"]:
+        print(f"\n✓ Successfully deployed {len(results['deployed'])} agents to {results['target_dir']}")
+        for agent in results["deployed"]:
+            print(f"  - {agent['name']}")
+    
+    if force and results.get("updated", []):
+        print(f"\n✓ Updated {len(results['updated'])} agents")
+        for agent in results["updated"]:
+            print(f"  - {agent['name']}")
+    
+    if force and results.get("skipped", []):
+        print(f"\n✓ Skipped {len(results['skipped'])} up-to-date agents")
+    
+    if results["errors"]:
+        print("\n❌ Errors during deployment:")
+        for error in results["errors"]:
+            print(f"  - {error}")
+    
+    if force:
+        # Set environment for force deploy
+        env_vars = deployment_service.set_claude_environment(
+            args.target.parent if args.target else None
+        )
+        print(f"\n✓ Set Claude environment variables:")
+        for key, value in env_vars.items():
+            print(f"  - {key}={value}")
+
+
+def _clean_agents(args, deployment_service):
+    """
+    Clean deployed system agents.
+    
+    WHY: Users may want to remove deployed agents to start fresh or clean up
+    their working directory.
+    
+    Args:
+        args: Command arguments with optional 'target' path
+        deployment_service: Agent deployment service instance
+    """
+    print("Cleaning deployed system agents...")
+    results = deployment_service.clean_deployment(args.target)
+    
+    if results["removed"]:
+        print(f"\n✓ Removed {len(results['removed'])} agents")
+        for path in results["removed"]:
+            print(f"  - {Path(path).name}")
+    else:
+        print("No system agents found to remove")
+    
+    if results["errors"]:
+        print("\n❌ Errors during cleanup:")
+        for error in results["errors"]:
+            print(f"  - {error}")

claude_mpm-3.1.2/src/claude_mpm/cli/commands/info.py

@@ -0,0 +1,89 @@
+"""
+Info command implementation for claude-mpm.
+
+WHY: This module provides system information and configuration details to help
+users understand their claude-mpm setup and troubleshoot issues.
+"""
+
+import shutil
+from pathlib import Path
+
+from ...core.logger import get_logger
+
+
+def show_info(args):
+    """
+    Show framework and configuration information.
+    
+    WHY: Users need to verify their installation, check dependencies, and understand
+    what agents are available. This command provides a comprehensive overview of
+    the claude-mpm environment.
+    
+    DESIGN DECISION: We check for all major components and dependencies, showing
+    both what's working (✓) and what's missing (✗) to help with troubleshooting.
+    
+    Args:
+        args: Parsed command line arguments
+    """
+    try:
+        from ...core.framework_loader import FrameworkLoader
+    except ImportError:
+        from claude_mpm.core.framework_loader import FrameworkLoader
+    
+    print("Claude MPM - Multi-Agent Project Manager")
+    print("=" * 50)
+    
+    # Framework info
+    loader = FrameworkLoader(args.framework_path)
+    if loader.framework_content["loaded"]:
+        print(f"Framework: claude-multiagent-pm")
+        print(f"Version: {loader.framework_content['version']}")
+        print(f"Path: {loader.framework_path}")
+        print(f"Agents: {', '.join(loader.get_agent_list())}")
+    else:
+        print("Framework: Not found (using minimal instructions)")
+    
+    print()
+    
+    # Configuration
+    print("Configuration:")
+    print(f"  Log directory: {args.log_dir or '~/.claude-mpm/logs'}")
+    print(f"  Debug mode: {args.debug}")
+    
+    # Show agent hierarchy
+    if loader.agent_registry:
+        hierarchy = loader.agent_registry.get_agent_hierarchy()
+        print("\nAgent Hierarchy:")
+        print(f"  Project agents: {len(hierarchy['project'])}")
+        print(f"  User agents: {len(hierarchy['user'])}")
+        print(f"  System agents: {len(hierarchy['system'])}")
+        
+        # Show core agents
+        core_agents = loader.agent_registry.get_core_agents()
+        print(f"\nCore Agents: {', '.join(core_agents)}")
+    
+    # Check dependencies
+    print("\nDependencies:")
+    
+    # Check Claude CLI
+    claude_path = shutil.which("claude")
+    if claude_path:
+        print(f"  ✓ Claude CLI: {claude_path}")
+    else:
+        print("  ✗ Claude CLI: Not found in PATH")
+    
+    # Check ai-trackdown-pytools
+    try:
+        import ai_trackdown_pytools
+        print("  ✓ ai-trackdown-pytools: Installed")
+    except ImportError:
+        print("  ✗ ai-trackdown-pytools: Not installed")
+    
+    # Check Claude Code hooks
+    claude_settings = Path.home() / ".claude" / "settings.json"
+    if claude_settings.exists():
+        print("  ✓ Claude Code Hooks: Installed")
+        print("     Use /mpm commands in Claude Code")
+    else:
+        print("  ✗ Claude Code Hooks: Not installed")
+        print("     Run: python scripts/install_hooks.py")

claude_mpm-3.1.2/src/claude_mpm/cli/commands/run.py

@@ -0,0 +1,80 @@
+"""
+Run command implementation for claude-mpm.
+
+WHY: This module handles the main 'run' command which starts Claude sessions.
+It's the most commonly used command and handles both interactive and non-interactive modes.
+"""
+
+import subprocess
+import sys
+from pathlib import Path
+
+from ...core.logger import get_logger
+from ...constants import LogLevel
+from ..utils import get_user_input, list_agent_versions_at_startup
+
+
+def run_session(args):
+    """
+    Run a simplified Claude session.
+    
+    WHY: This is the primary command that users interact with. It sets up the
+    environment, optionally deploys agents, and launches Claude with the MPM framework.
+    
+    DESIGN DECISION: We use SimpleClaudeRunner to handle the complexity of
+    subprocess management and hook integration, keeping this function focused
+    on high-level orchestration.
+    
+    Args:
+        args: Parsed command line arguments
+    """
+    logger = get_logger("cli")
+    if args.logging != LogLevel.OFF.value:
+        logger.info("Starting Claude MPM session")
+    
+    try:
+        from ...core.simple_runner import SimpleClaudeRunner, create_simple_context
+    except ImportError:
+        from claude_mpm.core.simple_runner import SimpleClaudeRunner, create_simple_context
+    
+    # Skip native agents if disabled
+    if getattr(args, 'no_native_agents', False):
+        print("Native agents disabled")
+    else:
+        # List deployed agent versions at startup
+        list_agent_versions_at_startup()
+    
+    # Create simple runner
+    enable_tickets = not args.no_tickets
+    claude_args = getattr(args, 'claude_args', []) or []
+    runner = SimpleClaudeRunner(
+        enable_tickets=enable_tickets,
+        log_level=args.logging,
+        claude_args=claude_args
+    )
+    
+    # Create basic context
+    context = create_simple_context()
+    
+    # Run session based on mode
+    if args.non_interactive or args.input:
+        # Non-interactive mode
+        user_input = get_user_input(args.input, logger)
+        success = runner.run_oneshot(user_input, context)
+        if not success:
+            logger.error("Session failed")
+    else:
+        # Interactive mode
+        if getattr(args, 'intercept_commands', False):
+            # Use the interactive wrapper for command interception
+            # WHY: Command interception requires special handling of stdin/stdout
+            # which is better done in a separate Python script
+            wrapper_path = Path(__file__).parent.parent.parent.parent.parent / "scripts" / "interactive_wrapper.py"
+            if wrapper_path.exists():
+                print("Starting interactive session with command interception...")
+                subprocess.run([sys.executable, str(wrapper_path)])
+            else:
+                logger.warning("Interactive wrapper not found, falling back to normal mode")
+                runner.run_interactive(context)
+        else:
+            runner.run_interactive(context)