claude-mpm 3.5.2__py3-none-any.whl → 3.5.6__py3-none-any.whl

claude_mpm/cli/README.md

@@ -0,0 +1,108 @@
+# 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
+└── 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/commands/agents.py

@@ -6,10 +6,15 @@ and cleaning agent deployments.
 """
 
 from pathlib import Path
+import json
+import yaml
+from typing import Dict, Any, Optional
 
 from ...core.logger import get_logger
 from ...constants import AgentCommands
 from ..utils import get_agent_versions_display
+from ...core.agent_registry import AgentRegistryAdapter
+from ...agents.frontmatter_validator import FrontmatterValidator
 
 
 def manage_agents(args):
@@ -29,7 +34,16 @@ def manage_agents(args):
     
     try:
         from ...services import AgentDeploymentService
-        deployment_service = AgentDeploymentService()
+        import os
+        from pathlib import Path
+        
+        # Determine the user's working directory from environment
+        # This ensures agents are deployed to the correct directory
+        user_working_dir = None
+        if 'CLAUDE_MPM_USER_PWD' in os.environ:
+            user_working_dir = Path(os.environ['CLAUDE_MPM_USER_PWD'])
+        
+        deployment_service = AgentDeploymentService(working_directory=user_working_dir)
         
         if not args.agents_command:
             # No subcommand - show agent versions
@@ -55,6 +69,12 @@ def manage_agents(args):
         elif args.agents_command == AgentCommands.CLEAN.value:
             _clean_agents(args, deployment_service)
         
+        elif args.agents_command == AgentCommands.VIEW.value:
+            _view_agent(args)
+        
+        elif args.agents_command == AgentCommands.FIX.value:
+            _fix_agents(args)
+        
     except ImportError:
         logger.error("Agent deployment service not available")
         print("Error: Agent deployment service not available")
@@ -71,10 +91,13 @@ def _list_agents(args, deployment_service):
     currently deployed. This helps them understand the agent ecosystem.
     
     Args:
-        args: Command arguments with 'system' and 'deployed' flags
+        args: Command arguments with 'system', 'deployed', and 'by_tier' flags
         deployment_service: Agent deployment service instance
     """
-    if args.system:
+    if hasattr(args, 'by_tier') and args.by_tier:
+        # List agents grouped by tier
+        _list_agents_by_tier()
+    elif args.system:
         # List available agent templates
         print("Available Agent Templates:")
         print("-" * 80)
@@ -114,21 +137,22 @@ def _list_agents(args, deployment_service):
     
     else:
         # Default: show usage
-        print("Use --system to list system agents or --deployed to list deployed agents")
+        print("Use --system to list system agents, --deployed to list deployed agents, or --by-tier to group by precedence")
 
 
 def _deploy_agents(args, deployment_service, force=False):
     """
-    Deploy system agents.
+    Deploy both system and project 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.
+    This function handles both regular and forced deployment, including project-specific agents.
     
     Args:
         args: Command arguments with optional 'target' path
         deployment_service: Agent deployment service instance
         force: Whether to force rebuild all agents
     """
+    # Deploy system agents first
     if force:
         print("Force deploying all system agents...")
     else:
@@ -136,6 +160,43 @@ def _deploy_agents(args, deployment_service, force=False):
     
     results = deployment_service.deploy_agents(args.target, force_rebuild=force)
     
+    # Also deploy project agents if they exist
+    from pathlib import Path
+    import os
+    
+    # Use the user's working directory if available
+    if 'CLAUDE_MPM_USER_PWD' in os.environ:
+        project_dir = Path(os.environ['CLAUDE_MPM_USER_PWD'])
+    else:
+        project_dir = Path.cwd()
+    
+    project_agents_dir = project_dir / '.claude-mpm' / 'agents'
+    if project_agents_dir.exists():
+        json_files = list(project_agents_dir.glob('*.json'))
+        if json_files:
+            print(f"\nDeploying {len(json_files)} project agents...")
+            from claude_mpm.services.agents.deployment.agent_deployment import AgentDeploymentService
+            project_service = AgentDeploymentService(
+                templates_dir=project_agents_dir,
+                base_agent_path=project_agents_dir / 'base_agent.json' if (project_agents_dir / 'base_agent.json').exists() else None,
+                working_directory=project_dir  # Pass the project directory
+            )
+            project_results = project_service.deploy_agents(
+                target_dir=args.target if args.target else Path.cwd() / '.claude' / 'agents',
+                force_rebuild=force,
+                deployment_mode='project'
+            )
+            
+            # Merge project results into main results
+            if project_results.get('deployed'):
+                results['deployed'].extend(project_results['deployed'])
+                print(f"✓ Deployed {len(project_results['deployed'])} project agents")
+            if project_results.get('updated'):
+                results['updated'].extend(project_results['updated'])
+                print(f"✓ Updated {len(project_results['updated'])} project agents")
+            if project_results.get('errors'):
+                results['errors'].extend(project_results['errors'])
+    
     if results["deployed"]:
         print(f"\n✓ Successfully deployed {len(results['deployed'])} agents to {results['target_dir']}")
         for agent in results["deployed"]:
@@ -188,4 +249,309 @@ def _clean_agents(args, deployment_service):
     if results["errors"]:
         print("\n❌ Errors during cleanup:")
         for error in results["errors"]:
-            print(f"  - {error}")
+            print(f"  - {error}")
+
+
+def _list_agents_by_tier():
+    """
+    List agents grouped by precedence tier.
+    
+    WHY: Users need to understand which agents are active across different tiers
+    and which version takes precedence when multiple versions exist.
+    """
+    try:
+        adapter = AgentRegistryAdapter()
+        if not adapter.registry:
+            print("❌ Could not initialize agent registry")
+            return
+        
+        # Get all agents and group by tier
+        all_agents = adapter.registry.list_agents()
+        
+        # Group agents by tier and name
+        tiers = {'project': {}, 'user': {}, 'system': {}}
+        agent_names = set()
+        
+        for agent_id, metadata in all_agents.items():
+            tier = metadata.get('tier', 'system')
+            if tier in tiers:
+                tiers[tier][agent_id] = metadata
+                agent_names.add(agent_id)
+        
+        # Display header
+        print("\n" + "=" * 80)
+        print(" " * 25 + "AGENT HIERARCHY BY TIER")
+        print("=" * 80)
+        print("\nPrecedence: PROJECT > USER > SYSTEM")
+        print("(Agents in higher tiers override those in lower tiers)\n")
+        
+        # Display each tier
+        tier_order = [('PROJECT', 'project'), ('USER', 'user'), ('SYSTEM', 'system')]
+        
+        for tier_display, tier_key in tier_order:
+            agents = tiers[tier_key]
+            print(f"\n{'─' * 35} {tier_display} TIER {'─' * 35}")
+            
+            if not agents:
+                print(f"  No agents at {tier_key} level")
+            else:
+                # Check paths to determine actual locations
+                if tier_key == 'project':
+                    print(f"  Location: .claude-mpm/agents/ (in current project)")
+                elif tier_key == 'user':
+                    print(f"  Location: ~/.claude-mpm/agents/")
+                else:
+                    print(f"  Location: Built-in framework agents")
+                
+                print(f"\n  Found {len(agents)} agent(s):\n")
+                
+                for agent_id, metadata in sorted(agents.items()):
+                    # Check if this agent is overridden by higher tiers
+                    is_active = True
+                    overridden_by = []
+                    
+                    for check_tier_display, check_tier_key in tier_order:
+                        if check_tier_key == tier_key:
+                            break
+                        if agent_id in tiers[check_tier_key]:
+                            is_active = False
+                            overridden_by.append(check_tier_display)
+                    
+                    # Display agent info
+                    status = "✓ ACTIVE" if is_active else f"⊗ OVERRIDDEN by {', '.join(overridden_by)}"
+                    print(f"    📄 {agent_id:<20} [{status}]")
+                    
+                    # Show metadata
+                    if 'description' in metadata:
+                        print(f"       Description: {metadata['description']}")
+                    if 'path' in metadata:
+                        path = Path(metadata['path'])
+                        print(f"       File: {path.name}")
+                    print()
+        
+        # Summary
+        print("\n" + "=" * 80)
+        print("SUMMARY:")
+        print(f"  Total unique agents: {len(agent_names)}")
+        print(f"  Project agents: {len(tiers['project'])}")
+        print(f"  User agents: {len(tiers['user'])}")
+        print(f"  System agents: {len(tiers['system'])}")
+        print("=" * 80 + "\n")
+        
+    except Exception as e:
+        print(f"❌ Error listing agents by tier: {e}")
+
+
+def _view_agent(args):
+    """
+    View detailed information about a specific agent.
+    
+    WHY: Users need to inspect agent configurations, frontmatter, and instructions
+    to understand what an agent does and how it's configured.
+    
+    Args:
+        args: Command arguments with 'agent_name' attribute
+    """
+    if not hasattr(args, 'agent_name') or not args.agent_name:
+        print("❌ Please specify an agent name to view")
+        print("Usage: claude-mpm agents view <agent_name>")
+        return
+    
+    try:
+        adapter = AgentRegistryAdapter()
+        if not adapter.registry:
+            print("❌ Could not initialize agent registry")
+            return
+        
+        # Get the agent
+        agent = adapter.registry.get_agent(args.agent_name)
+        if not agent:
+            print(f"❌ Agent '{args.agent_name}' not found")
+            print("\nAvailable agents:")
+            all_agents = adapter.registry.list_agents()
+            for agent_id in sorted(all_agents.keys()):
+                print(f"  - {agent_id}")
+            return
+        
+        # Read the agent file
+        agent_path = Path(agent.path)
+        if not agent_path.exists():
+            print(f"❌ Agent file not found: {agent_path}")
+            return
+        
+        with open(agent_path, 'r') as f:
+            content = f.read()
+        
+        # Display agent information
+        print("\n" + "=" * 80)
+        print(f" AGENT: {agent.name}")
+        print("=" * 80)
+        
+        # Basic info
+        print(f"\n📋 BASIC INFORMATION:")
+        print(f"  Name: {agent.name}")
+        print(f"  Type: {agent.type}")
+        print(f"  Tier: {agent.tier.upper()}")
+        print(f"  Path: {agent_path}")
+        if agent.description:
+            print(f"  Description: {agent.description}")
+        if agent.specializations:
+            print(f"  Specializations: {', '.join(agent.specializations)}")
+        
+        # Extract and display frontmatter
+        if content.startswith("---"):
+            try:
+                end_marker = content.find("\n---\n", 4)
+                if end_marker == -1:
+                    end_marker = content.find("\n---\r\n", 4)
+                
+                if end_marker != -1:
+                    frontmatter_str = content[4:end_marker]
+                    frontmatter = yaml.safe_load(frontmatter_str)
+                    
+                    print(f"\n📝 FRONTMATTER:")
+                    for key, value in frontmatter.items():
+                        if isinstance(value, list):
+                            print(f"  {key}: [{', '.join(str(v) for v in value)}]")
+                        elif isinstance(value, dict):
+                            print(f"  {key}:")
+                            for k, v in value.items():
+                                print(f"    {k}: {v}")
+                        else:
+                            print(f"  {key}: {value}")
+                    
+                    # Extract instructions preview
+                    instructions_start = end_marker + 5
+                    instructions = content[instructions_start:].strip()
+                    
+                    if instructions:
+                        print(f"\n📖 INSTRUCTIONS PREVIEW (first 500 chars):")
+                        print("  " + "-" * 76)
+                        preview = instructions[:500]
+                        if len(instructions) > 500:
+                            preview += "...\n\n  [Truncated - {:.1f}KB total]".format(len(instructions) / 1024)
+                        
+                        for line in preview.split('\n'):
+                            print(f"  {line}")
+                        print("  " + "-" * 76)
+            except Exception as e:
+                print(f"\n⚠️  Could not parse frontmatter: {e}")
+        else:
+            print(f"\n⚠️  No frontmatter found in agent file")
+        
+        # File stats
+        import os
+        stat = os.stat(agent_path)
+        from datetime import datetime
+        modified = datetime.fromtimestamp(stat.st_mtime).strftime("%Y-%m-%d %H:%M:%S")
+        print(f"\n📊 FILE STATS:")
+        print(f"  Size: {stat.st_size:,} bytes")
+        print(f"  Last modified: {modified}")
+        
+        print("\n" + "=" * 80 + "\n")
+        
+    except Exception as e:
+        print(f"❌ Error viewing agent: {e}")
+
+
+def _fix_agents(args):
+    """
+    Fix agent frontmatter issues using FrontmatterValidator.
+    
+    WHY: Agent files may have formatting issues in their frontmatter that prevent
+    proper loading. This command automatically fixes common issues.
+    
+    Args:
+        args: Command arguments with 'agent_name', 'dry_run', and 'all' flags
+    """
+    validator = FrontmatterValidator()
+    
+    try:
+        adapter = AgentRegistryAdapter()
+        if not adapter.registry:
+            print("❌ Could not initialize agent registry")
+            return
+        
+        # Determine which agents to fix
+        agents_to_fix = []
+        
+        if hasattr(args, 'all') and args.all:
+            # Fix all agents
+            all_agents = adapter.registry.list_agents()
+            for agent_id, metadata in all_agents.items():
+                agents_to_fix.append((agent_id, metadata['path']))
+            print(f"\n🔧 Checking {len(agents_to_fix)} agent(s) for frontmatter issues...\n")
+        elif hasattr(args, 'agent_name') and args.agent_name:
+            # Fix specific agent
+            agent = adapter.registry.get_agent(args.agent_name)
+            if not agent:
+                print(f"❌ Agent '{args.agent_name}' not found")
+                return
+            agents_to_fix.append((agent.name, agent.path))
+            print(f"\n🔧 Checking agent '{agent.name}' for frontmatter issues...\n")
+        else:
+            print("❌ Please specify an agent name or use --all to fix all agents")
+            print("Usage: claude-mpm agents fix [agent_name] [--dry-run] [--all]")
+            return
+        
+        dry_run = hasattr(args, 'dry_run') and args.dry_run
+        if dry_run:
+            print("🔍 DRY RUN MODE - No changes will be made\n")
+        
+        # Process each agent
+        total_issues = 0
+        total_fixed = 0
+        
+        for agent_name, agent_path in agents_to_fix:
+            path = Path(agent_path)
+            if not path.exists():
+                print(f"⚠️  Skipping {agent_name}: File not found at {path}")
+                continue
+            
+            print(f"📄 {agent_name}:")
+            
+            # Validate and potentially fix
+            result = validator.correct_file(path, dry_run=dry_run)
+            
+            if result.is_valid and not result.corrections:
+                print("  ✓ No issues found")
+            else:
+                if result.errors:
+                    print("  ❌ Errors:")
+                    for error in result.errors:
+                        print(f"    - {error}")
+                    total_issues += len(result.errors)
+                
+                if result.warnings:
+                    print("  ⚠️  Warnings:")
+                    for warning in result.warnings:
+                        print(f"    - {warning}")
+                    total_issues += len(result.warnings)
+                
+                if result.corrections:
+                    if dry_run:
+                        print("  🔧 Would fix:")
+                    else:
+                        print("  ✓ Fixed:")
+                        total_fixed += len(result.corrections)
+                    for correction in result.corrections:
+                        print(f"    - {correction}")
+            
+            print()
+        
+        # Summary
+        print("=" * 80)
+        print("SUMMARY:")
+        print(f"  Agents checked: {len(agents_to_fix)}")
+        print(f"  Total issues found: {total_issues}")
+        if dry_run:
+            print(f"  Issues that would be fixed: {sum(1 for _, path in agents_to_fix if validator.validate_file(Path(path)).corrections)}")
+            print("\n💡 Run without --dry-run to apply fixes")
+        else:
+            print(f"  Issues fixed: {total_fixed}")
+            if total_fixed > 0:
+                print("\n✓ Frontmatter issues have been fixed!")
+        print("=" * 80 + "\n")
+        
+    except Exception as e:
+        print(f"❌ Error fixing agents: {e}")

claude_mpm/cli/commands/run.py

@@ -281,17 +281,10 @@ def run_session(args):
         websocket_port=websocket_port
     )
     
-    # Ensure project agents are available if we're in a project directory
-    # This deploys system agents to .claude-mpm/agents/ for local customization
-    if not hasattr(args, 'no_native_agents') or not args.no_native_agents:
-        # Check if we're in a project directory (has .git or other markers)
-        project_markers = ['.git', 'pyproject.toml', 'package.json', 'requirements.txt']
-        cwd = Path.cwd()
-        is_project = any((cwd / marker).exists() for marker in project_markers)
-        
-        if is_project:
-            logger.debug("Detected project directory, ensuring agents are available locally")
-            runner.ensure_project_agents()
+    # Agent deployment is handled by ClaudeRunner.setup_agents() and 
+    # ClaudeRunner.deploy_project_agents_to_claude() which are called
+    # in both run_interactive() and run_oneshot() methods.
+    # No need for redundant deployment here.
     
     # Set browser opening flag for monitor mode
     if monitor_mode:

claude_mpm/cli/parser.py

@@ -306,6 +306,42 @@ def create_parser(prog_name: str = "claude-mpm", version: str = "0.0.0") -> argp
         action="store_true", 
         help="List deployed agents"
     )
+    list_agents_parser.add_argument(
+        "--by-tier",
+        action="store_true",
+        help="List agents grouped by precedence tier (PROJECT > USER > SYSTEM)"
+    )
+    
+    # View agent details
+    view_agent_parser = agents_subparsers.add_parser(
+        AgentCommands.VIEW.value,
+        help="View detailed information about a specific agent"
+    )
+    view_agent_parser.add_argument(
+        "agent_name",
+        help="Name of the agent to view"
+    )
+    
+    # Fix agent frontmatter
+    fix_agents_parser = agents_subparsers.add_parser(
+        AgentCommands.FIX.value,
+        help="Fix agent frontmatter issues"
+    )
+    fix_agents_parser.add_argument(
+        "agent_name",
+        nargs="?",
+        help="Name of specific agent to fix (fix all if not specified with --all)"
+    )
+    fix_agents_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Preview changes without applying them"
+    )
+    fix_agents_parser.add_argument(
+        "--all",
+        action="store_true",
+        help="Fix all agents"
+    )
     
     # Deploy agents
     deploy_agents_parser = agents_subparsers.add_parser(

claude_mpm/cli/utils.py

@@ -61,7 +61,15 @@ def get_agent_versions_display() -> Optional[str]:
     """
     try:
         from ..services import AgentDeploymentService
-        deployment_service = AgentDeploymentService()
+        import os
+        from pathlib import Path
+        
+        # Determine the user's working directory from environment
+        user_working_dir = None
+        if 'CLAUDE_MPM_USER_PWD' in os.environ:
+            user_working_dir = Path(os.environ['CLAUDE_MPM_USER_PWD'])
+        
+        deployment_service = AgentDeploymentService(working_directory=user_working_dir)
         
         # Get deployed agents
         verification = deployment_service.verify_deployment()