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

claude_mpm/cli_module/refactoring_guide.md

@@ -0,0 +1,253 @@
+# CLI Refactoring Guide
+
+This guide shows how to refactor the main() function in `/src/claude_mpm/cli.py` to reduce complexity from 16 to under 10.
+
+## Current Issues
+
+1. **High Cyclomatic Complexity (16)**
+   - Multiple nested conditionals
+   - Duplicate argument definitions
+   - Mixed concerns in one function
+
+2. **Code Duplication**
+   - Arguments defined twice (global level + run subcommand)
+   - Similar patterns repeated for each command
+
+3. **Poor Maintainability**
+   - Adding new commands requires multiple changes
+   - Hard to test individual components
+
+## Refactoring Steps
+
+### Step 1: Update imports in cli.py
+
+```python
+# Add to imports
+from .cli import ArgumentRegistry, CommandRegistry, register_standard_commands
+```
+
+### Step 2: Replace main() function
+
+Replace the entire `main()` function with:
+
+```python
+def main(argv: Optional[list] = None):
+    """Main CLI entry point with reduced complexity."""
+    # Initialize registries
+    arg_registry = ArgumentRegistry()
+    cmd_registry = CommandRegistry(arg_registry)
+    
+    # Register standard commands
+    register_standard_commands(cmd_registry)
+    
+    # Create parser
+    parser = argparse.ArgumentParser(
+        prog="claude-mpm",
+        description=f"Claude Multi-Agent Project Manager v{__version__}",
+        epilog="By default, runs an orchestrated Claude session."
+    )
+    
+    # Store version for ArgumentRegistry
+    parser._version = f"claude-mpm {__version__}"
+    
+    # Apply global arguments
+    arg_registry.apply_arguments(parser, groups=['global'])
+    
+    # Apply run arguments at top level (for default behavior)
+    arg_registry.apply_arguments(parser, groups=['run'], exclude=['no_hooks'])
+    
+    # Set up subcommands
+    cmd_registry.setup_subcommands(parser)
+    
+    # Parse arguments
+    args = parser.parse_args(argv)
+    
+    # Set up logging
+    _setup_logging(args)
+    
+    # Initialize hook service
+    hook_manager = _initialize_hook_service(args)
+    
+    try:
+        # Execute command
+        result = cmd_registry.execute_command(args, hook_manager=hook_manager)
+        if result is None and not args.command:
+            parser.print_help()
+            return 1
+        return result or 0
+        
+    except KeyboardInterrupt:
+        get_logger("cli").info("Session interrupted by user")
+        return 0
+    except Exception as e:
+        logger = get_logger("cli")
+        logger.error(f"Error: {e}")
+        if args.debug:
+            import traceback
+            traceback.print_exc()
+        return 1
+    finally:
+        if hook_manager:
+            hook_manager.stop_service()
+```
+
+### Step 3: Extract helper functions
+
+Add these helper functions after main():
+
+```python
+def _setup_logging(args):
+    """Set up logging based on arguments."""
+    if args.debug and args.logging == "OFF":
+        args.logging = "DEBUG"
+    
+    if args.logging != "OFF":
+        setup_logging(level=args.logging, log_dir=args.log_dir)
+    else:
+        import logging
+        logger = logging.getLogger("cli")
+        logger.setLevel(logging.WARNING)
+
+
+def _initialize_hook_service(args):
+    """Initialize hook service if enabled."""
+    if getattr(args, 'no_hooks', False):
+        return None
+        
+    try:
+        from .config.hook_config import HookConfig
+        
+        if not HookConfig.is_hooks_enabled():
+            get_logger("cli").info("Hooks disabled via configuration")
+            return None
+            
+        hook_manager = HookServiceManager(log_dir=args.log_dir)
+        if hook_manager.start_service():
+            logger = get_logger("cli")
+            logger.info(f"Hook service started on port {hook_manager.port}")
+            print(f"Hook service started on port {hook_manager.port}")
+            return hook_manager
+        else:
+            logger = get_logger("cli")
+            logger.warning("Failed to start hook service")
+            print("Failed to start hook service, continuing without hooks")
+            return None
+            
+    except Exception as e:
+        get_logger("cli").warning(f"Hook service init failed: {e}")
+        return None
+```
+
+### Step 4: Update command handler signatures
+
+Ensure all command handlers accept `**kwargs`:
+
+```python
+def run_session(args, hook_manager=None, **kwargs):
+    """Run an orchestrated Claude session."""
+    # ... existing implementation
+
+def list_tickets(args, **kwargs):
+    """List recent tickets."""
+    # ... existing implementation
+
+def show_info(args, hook_manager=None, **kwargs):
+    """Show framework and configuration information."""
+    # ... existing implementation
+```
+
+## Benefits Achieved
+
+### Complexity Reduction
+- **Before**: Cyclomatic complexity of 16
+- **After**: Cyclomatic complexity of ~8
+
+### Code Organization
+- Centralized argument definitions
+- No duplicate argument definitions
+- Clear separation of concerns
+- Easier to add new commands
+
+### Maintainability
+- New commands can be added with a single `register()` call
+- Arguments are defined once and reused
+- Helper functions are testable in isolation
+- Registry pattern allows for extension
+
+## Adding New Commands
+
+With the registry system, adding a new command is simple:
+
+```python
+# In your code or plugin
+def my_command(args, **kwargs):
+    """Implementation of your command."""
+    print(f"Running my command with args: {args}")
+    return 0
+
+# Register it
+cmd_registry.register(
+    name='mycommand',
+    help_text='Description of my command',
+    handler=my_command,
+    argument_groups=['framework'],  # Reuse existing argument groups
+    extra_args={
+        'custom_arg': {
+            'flags': ['--custom'],
+            'type': str,
+            'help': 'A custom argument for this command'
+        }
+    }
+)
+```
+
+## Testing
+
+The refactored code is easier to test:
+
+```python
+# Test argument registry
+def test_argument_registry():
+    registry = ArgumentRegistry()
+    parser = argparse.ArgumentParser()
+    registry.apply_arguments(parser, groups=['logging'])
+    
+    # Verify logging arguments were added
+    args = parser.parse_args(['--logging', 'DEBUG'])
+    assert args.logging == 'DEBUG'
+
+# Test command registry
+def test_command_registry():
+    arg_reg = ArgumentRegistry()
+    cmd_reg = CommandRegistry(arg_reg)
+    
+    called = False
+    def test_handler(args, **kwargs):
+        nonlocal called
+        called = True
+        return 0
+    
+    cmd_reg.register('test', 'Test command', test_handler)
+    
+    parser = argparse.ArgumentParser()
+    cmd_reg.setup_subcommands(parser)
+    
+    args = parser.parse_args(['test'])
+    result = cmd_reg.execute_command(args)
+    
+    assert called
+    assert result == 0
+```
+
+## Migration Checklist
+
+- [ ] Create `/src/claude_mpm/cli/` directory
+- [ ] Create `args.py` with ArgumentRegistry
+- [ ] Create `commands.py` with CommandRegistry
+- [ ] Create `__init__.py` to export classes
+- [ ] Update imports in `cli.py`
+- [ ] Replace main() function
+- [ ] Add helper functions
+- [ ] Update command handler signatures
+- [ ] Test the refactored CLI
+- [ ] Verify complexity is reduced to ≤10

claude_mpm/config/async_logging_config.yaml

@@ -0,0 +1,145 @@
+# Async Logging Configuration
+# Optimized logging configuration for high-performance scenarios
+
+logging:
+  # Enable async logging for improved performance
+  async:
+    enabled: true
+    
+    # Log format options: json, syslog, journald
+    format: json
+    
+    # Maximum queue size for async writes
+    max_queue_size: 10000
+    
+    # Enable compression for JSON logs (reduces disk usage)
+    compression: false
+    
+    # Worker threads for async processing
+    worker_threads: 4
+    
+    # Flush timeout in seconds
+    flush_timeout: 5.0
+  
+  # Session logger settings
+  session:
+    # Base directory for logs
+    base_dir: ".claude-mpm/responses"
+    
+    # Use timestamp-based filenames (eliminates race conditions)
+    timestamp_filenames: true
+    
+    # Include microseconds in timestamps for uniqueness
+    microsecond_precision: true
+    
+    # Filename format with available variables:
+    # {agent} - Agent name
+    # {timestamp} - ISO timestamp
+    # {microseconds} - Microsecond component
+    # {session} - Session ID
+    filename_format: "{agent}_{timestamp}_{microseconds}.json"
+  
+  # OS-native logging options (for extreme performance)
+  syslog:
+    # Syslog address (auto-detected by default)
+    # address: /var/run/syslog  # macOS
+    # address: /dev/log         # Linux
+    # address: ["localhost", 514]  # Network
+    
+    # Syslog facility
+    facility: local0
+    
+    # Include structured data
+    structured_data: true
+  
+  # Performance tuning
+  performance:
+    # Fire-and-forget mode (don't wait for write confirmation)
+    fire_and_forget: true
+    
+    # Drop logs if queue is full (prevents blocking)
+    drop_on_full: true
+    
+    # Batch writes for efficiency
+    batch_writes: true
+    batch_size: 10
+    batch_timeout_ms: 100
+
+# Hook system optimization
+hooks:
+  # Enable hook system
+  enabled: true
+  
+  # Optimization settings
+  optimization:
+    # Cache hook configurations at startup
+    cache_configs: true
+    
+    # Lazy load hook implementations
+    lazy_loading: true
+    
+    # Use singleton pattern for hook service
+    singleton: true
+    
+    # Enable async hook execution
+    async_execution: true
+    
+    # Maximum workers for parallel hook execution
+    max_workers: 4
+  
+  # Pre-delegation hooks
+  pre_delegation:
+    enabled: true
+    
+    # Parallel execution for independent hooks
+    parallel_safe_hooks:
+      - memory_context_hook
+      - validation_hook
+      - auth_hook
+  
+  # Post-delegation hooks
+  post_delegation:
+    enabled: true
+    
+    # Parallel execution for independent hooks
+    parallel_safe_hooks:
+      - logging_hook
+      - metrics_hook
+      - cleanup_hook
+  
+  # Registered hooks with lazy loading
+  registered:
+    # NOTE: The builtin hooks have been deprecated and removed
+    # These references are kept commented for historical reference
+    # memory_context_hook:
+    #   module: claude_mpm.hooks.builtin.memory_hooks
+    #   class: MemoryContextHook
+    #   priority: 10
+    #   enabled: true
+    #   params:
+    #     cache_size: 1000
+    # 
+    # response_logger_hook:
+    #   module: claude_mpm.hooks.builtin.logging_hooks
+    #   class: ResponseLoggerHook
+    #   priority: 90
+    #   enabled: true
+    #   params:
+    #     async: true
+    # 
+    # metrics_hook:
+    #   module: claude_mpm.hooks.builtin.metrics_hooks
+    #   class: MetricsCollectorHook
+    #   priority: 95
+    #   enabled: true
+    #   params:
+    #     buffer_size: 100
+
+# Environment variable overrides
+# These can override any setting above:
+#
+# CLAUDE_USE_ASYNC_LOG=true        # Enable async logging
+# CLAUDE_LOG_FORMAT=syslog         # Use syslog format
+# CLAUDE_LOG_SYNC=true             # Disable async (for debugging)
+# CLAUDE_HOOKS_CACHE=true          # Enable hook caching
+# CLAUDE_HOOKS_ASYNC=true          # Enable async hooks

claude_mpm/constants.py

@@ -51,6 +51,8 @@ class CLICommands(str, Enum):
 class AgentCommands(str, Enum):
     """Agent subcommand constants."""
     LIST = "list"
+    VIEW = "view"
+    FIX = "fix"
     DEPLOY = "deploy"
     FORCE_DEPLOY = "force-deploy"
     CLEAN = "clean"

claude_mpm/core/.claude-mpm/logs/hooks_20250730.log

@@ -0,0 +1,34 @@
+2025-07-30 12:40:20,992 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PostToolUse (session: df539357)
+2025-07-30 12:40:20,992 - claude_mpm_hooks_core - INFO - hook_handler.py:254 - PostToolUse: Bash (exit code: N/A)
+2025-07-30 12:40:33,117 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PreToolUse (session: df539357)
+2025-07-30 12:40:33,117 - claude_mpm_hooks_core - INFO - hook_handler.py:247 - PreToolUse: Edit
+2025-07-30 12:40:33,276 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PostToolUse (session: df539357)
+2025-07-30 12:40:33,276 - claude_mpm_hooks_core - INFO - hook_handler.py:254 - PostToolUse: Edit (exit code: N/A)
+2025-07-30 12:40:39,276 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PreToolUse (session: df539357)
+2025-07-30 12:40:39,276 - claude_mpm_hooks_core - INFO - hook_handler.py:247 - PreToolUse: Bash
+2025-07-30 12:40:39,541 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PostToolUse (session: df539357)
+2025-07-30 12:40:39,541 - claude_mpm_hooks_core - INFO - hook_handler.py:254 - PostToolUse: Bash (exit code: N/A)
+2025-07-30 12:40:48,610 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PreToolUse (session: df539357)
+2025-07-30 12:40:48,610 - claude_mpm_hooks_core - INFO - hook_handler.py:247 - PreToolUse: Bash
+2025-07-30 12:40:49,941 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PostToolUse (session: df539357)
+2025-07-30 12:40:49,941 - claude_mpm_hooks_core - INFO - hook_handler.py:254 - PostToolUse: Bash (exit code: N/A)
+2025-07-30 12:44:50,358 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: UserPromptSubmit (session: df539357)
+2025-07-30 12:44:50,358 - claude_mpm_hooks_core - INFO - hook_handler.py:244 - UserPromptSubmit: OK. Let's make the subprocess the default method
+2025-07-30 13:05:35,872 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: UserPromptSubmit (session: df539357)
+2025-07-30 13:05:35,872 - claude_mpm_hooks_core - INFO - hook_handler.py:244 - UserPromptSubmit: actually leave as is.  I want to figure out a simple test to trigger the terminal flow.  Use docs/de...
+2025-07-30 13:05:42,930 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PreToolUse (session: df539357)
+2025-07-30 13:05:42,930 - claude_mpm_hooks_core - INFO - hook_handler.py:247 - PreToolUse: Read
+2025-07-30 13:05:43,133 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PostToolUse (session: df539357)
+2025-07-30 13:05:43,133 - claude_mpm_hooks_core - INFO - hook_handler.py:254 - PostToolUse: Read (exit code: N/A)
+2025-07-30 13:05:49,996 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PreToolUse (session: df539357)
+2025-07-30 13:05:49,996 - claude_mpm_hooks_core - INFO - hook_handler.py:247 - PreToolUse: Grep
+2025-07-30 13:05:50,548 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PostToolUse (session: df539357)
+2025-07-30 13:05:50,548 - claude_mpm_hooks_core - INFO - hook_handler.py:254 - PostToolUse: Grep (exit code: N/A)
+2025-07-30 13:05:56,341 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PreToolUse (session: df539357)
+2025-07-30 13:05:56,341 - claude_mpm_hooks_core - INFO - hook_handler.py:247 - PreToolUse: Read
+2025-07-30 13:05:56,527 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PostToolUse (session: df539357)
+2025-07-30 13:05:56,528 - claude_mpm_hooks_core - INFO - hook_handler.py:254 - PostToolUse: Read (exit code: N/A)
+2025-07-30 13:06:01,890 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PreToolUse (session: df539357)
+2025-07-30 13:06:01,890 - claude_mpm_hooks_core - INFO - hook_handler.py:247 - PreToolUse: Bash
+2025-07-30 13:06:08,115 - claude_mpm_hooks_core - INFO - hook_handler.py:231 - Claude Code hook event: PreToolUse (session: df539357)
+2025-07-30 13:06:08,115 - claude_mpm_hooks_core - INFO - hook_handler.py:247 - PreToolUse: Bash

claude_mpm/core/agent_registry.py

@@ -55,6 +55,9 @@ class SimpleAgentRegistry:
         # Check multiple possible locations, including project-level
         agent_locations = [
             # Project-level agents (highest priority)
+            # Project-level deployed agents (highest priority - what Claude Code uses)
+            Path.cwd() / ".claude" / "agents",
+            # Project-level source agents (fallback)
             Path.cwd() / ".claude-mpm" / "agents",
             # Framework/system agents
             self.framework_path / "src" / "claude_mpm" / "agents" / "templates",
@@ -98,7 +101,7 @@ class SimpleAgentRegistry:
     def _determine_tier(self, agent_path: Path) -> str:
         """Determine agent tier based on path."""
         path_str = str(agent_path)
-        if 'project' in path_str or '.claude-mpm' in path_str:
+        if 'project' in path_str or '.claude-mpm' in path_str or '.claude/agents' in path_str:
             return 'project'
         elif 'user' in path_str or str(Path.home()) in path_str:
             return 'user'