claude-mpm 3.1.0__py3-none-any.whl → 3.1.2__py3-none-any.whl

claude_mpm/__main__.py

@@ -1,13 +1,20 @@
-"""Main entry point for claude-mpm."""
+"""
+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
-import os
 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 cli
+# Import main function from the new CLI module structure
 from claude_mpm.cli import main
 
 if __name__ == "__main__":

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/cli/README.md

@@ -0,0 +1,109 @@
+# Claude MPM CLI Architecture
+
+This document describes the refactored CLI architecture for claude-mpm.
+
+## Overview
+
+The CLI has been refactored from a single monolithic `cli.py` file into a modular structure that improves maintainability and code organization.
+
+## Directory Structure
+
+```
+cli/
+├── __init__.py       # Main entry point - orchestrates the CLI flow
+├── parser.py         # Argument parsing logic - single source of truth for CLI arguments
+├── utils.py          # Shared utility functions
+├── commands/         # Individual command implementations
+│   ├── __init__.py
+│   ├── run.py        # Default command - runs Claude sessions
+│   ├── tickets.py    # Lists tickets
+│   ├── info.py       # Shows system information
+│   ├── agents.py     # Manages agent deployments
+│   └── ui.py         # Terminal UI launcher
+└── README.md         # This file
+```
+
+## Key Design Decisions
+
+### 1. Modular Command Structure
+Each command is implemented in its own module under `commands/`. This makes it easy to:
+- Add new commands without touching existing code
+- Test commands in isolation
+- Understand what each command does
+
+### 2. Centralized Argument Parsing
+All argument definitions are in `parser.py`. This provides:
+- Single source of truth for CLI arguments
+- Reusable argument groups (common arguments, run arguments)
+- Clear separation of parsing from execution
+
+### 3. Shared Utilities
+Common functions are in `utils.py`:
+- `get_user_input()` - Handles input from files, stdin, or command line
+- `get_agent_versions_display()` - Formats agent version information
+- `setup_logging()` - Configures logging based on arguments
+- `ensure_directories()` - Creates required directories on first run
+
+### 4. Backward Compatibility
+The refactoring maintains full backward compatibility:
+- `__main__.py` still imports from `claude_mpm.cli`
+- The main `cli/__init__.py` exports the same `main()` function
+- All existing commands and arguments work exactly as before
+
+## Entry Points
+
+1. **Package execution**: `python -m claude_mpm`
+   - Uses `__main__.py` which imports from `cli/__init__.py`
+
+2. **Direct import**: `from claude_mpm.cli import main`
+   - Imports the main function from `cli/__init__.py`
+
+3. **Shell script**: `claude-mpm` command
+   - Calls `python -m claude_mpm` with proper environment setup
+
+## Adding New Commands
+
+To add a new command:
+
+1. Create a new module in `commands/`:
+```python
+# commands/mycommand.py
+def my_command(args):
+    """Execute my command."""
+    # Implementation here
+```
+
+2. Add the command to `commands/__init__.py`:
+```python
+from .mycommand import my_command
+```
+
+3. Add parser configuration in `parser.py`:
+```python
+# In create_parser()
+mycommand_parser = subparsers.add_parser(
+    "mycommand",
+    help="Description of my command"
+)
+# Add command-specific arguments
+```
+
+4. Add the command mapping in `cli/__init__.py`:
+```python
+# In _execute_command()
+command_map = {
+    # ... existing commands ...
+    "mycommand": my_command,
+}
+```
+
+## Removed Files
+
+- `cli_main.py` - Redundant entry point, functionality moved to `__main__.py`
+- Original `cli.py` - Split into the modular structure described above
+
+## Preserved Files
+
+- `cli_enhancements.py` - Experimental Click-based CLI with enhanced features
+  - Kept for reference and future enhancement ideas
+  - Not currently used in production

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