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

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/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/claude_runner.py

@@ -74,8 +74,16 @@ class ClaudeRunner:
                 self.logger.warning(f"Failed to initialize project logger: {e}")
         
         # Initialize services with proper error handling
+        # 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'])
+            self.logger.info(f"Using user working directory from CLAUDE_MPM_USER_PWD: {user_working_dir}")
+        
         try:
-            self.deployment_service = AgentDeploymentService()
+            # Pass the user working directory to the deployment service
+            # This ensures agents are deployed to the correct user directory, not the framework directory
+            self.deployment_service = AgentDeploymentService(working_directory=user_working_dir)
         except ImportError as e:
             self.logger.error(f"Failed to import AgentDeploymentService: {e}")
             raise RuntimeError("Required module AgentDeploymentService not available. Please reinstall claude-mpm.") from e
@@ -253,8 +261,12 @@ class ClaudeRunner:
             bool: True if agents are available, False on error
         """
         try:
-            # Check if we're in a project directory
-            project_dir = Path.cwd()
+            # Use the correct user directory, not the framework directory
+            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"
             
             # Create directory if it doesn't exist
@@ -321,7 +333,12 @@ class ClaudeRunner:
             bool: True if deployment successful or no agents to deploy, False on error
         """
         try:
-            project_dir = Path.cwd()
+            # Use the correct user directory, not the framework directory
+            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"
             claude_agents_dir = project_dir / ".claude" / "agents"
             
@@ -352,9 +369,41 @@ class ClaudeRunner:
             errors = []
             
             # Deploy each JSON agent
+            # CRITICAL: PM (Project Manager) must NEVER be deployed as it's the main Claude instance
+            EXCLUDED_AGENTS = {'pm', 'project_manager'}
+            
+            # Initialize deployment service with proper base agent path
+            # Use the existing deployment service's base agent path if available
+            base_agent_path = project_agents_dir / "base_agent.json"
+            if not base_agent_path.exists():
+                # Fall back to system base agent
+                base_agent_path = self.deployment_service.base_agent_path
+            
+            # Create a single deployment service instance for all agents
+            project_deployment = AgentDeploymentService(
+                templates_dir=project_agents_dir,
+                base_agent_path=base_agent_path,
+                working_directory=project_dir  # Pass the project directory
+            )
+            
+            # Load base agent data once
+            base_agent_data = {}
+            if base_agent_path and base_agent_path.exists():
+                try:
+                    import json
+                    base_agent_data = json.loads(base_agent_path.read_text())
+                except Exception as e:
+                    self.logger.warning(f"Could not load base agent: {e}")
+            
             for json_file in json_files:
                 try:
                     agent_name = json_file.stem
+                    
+                    # Skip PM agent - it's the main Claude instance, not a subagent
+                    if agent_name.lower() in EXCLUDED_AGENTS:
+                        self.logger.info(f"Skipping {agent_name} (PM is the main Claude instance)")
+                        continue
+                    
                     target_file = claude_agents_dir / f"{agent_name}.md"
                     
                     # Check if agent needs update
@@ -369,26 +418,7 @@ class ClaudeRunner:
                                 self.logger.debug(f"Project agent {agent_name} is up to date")
                     
                     if needs_update:
-                        # Use deployment service to build the agent
-                        from claude_mpm.services.agents.deployment.agent_deployment import AgentDeploymentService
-                        
-                        # Create a temporary deployment service for this specific task
-                        project_deployment = AgentDeploymentService(
-                            templates_dir=project_agents_dir,
-                            base_agent_path=project_dir / ".claude-mpm" / "agents" / "base_agent.json"
-                        )
-                        
-                        # Load base agent data if available
-                        base_agent_data = {}
-                        base_agent_path = project_dir / ".claude-mpm" / "agents" / "base_agent.json"
-                        if base_agent_path.exists():
-                            import json
-                            try:
-                                base_agent_data = json.loads(base_agent_path.read_text())
-                            except Exception as e:
-                                self.logger.warning(f"Could not load project base agent: {e}")
-                        
-                        # Build the agent markdown
+                        # Build the agent markdown using the pre-initialized service and base agent data
                         agent_content = project_deployment._build_agent_markdown(
                             agent_name, json_file, base_agent_data
                         )
@@ -1063,17 +1093,46 @@ class ClaudeRunner:
     def _load_system_instructions(self) -> Optional[str]:
         """Load and process system instructions from agents/INSTRUCTIONS.md.
         
-        WHY: Process template variables like {{capabilities-list}} to include
-        dynamic agent capabilities in the PM's system instructions.
+        Implements project > framework precedence:
+        1. First check for project-specific instructions in .claude-mpm/agents/INSTRUCTIONS.md
+        2. If not found, fall back to framework instructions in src/claude_mpm/agents/INSTRUCTIONS.md
+        
+        WHY: Allows projects to override the default PM instructions with project-specific
+        guidance, while maintaining backward compatibility with the framework defaults.
+        
+        DESIGN DECISION: Using CLAUDE_MPM_USER_PWD environment variable to locate the
+        correct project directory, ensuring we check the right location even when
+        claude-mpm is invoked from a different directory.
         """
         try:
-            # Find the INSTRUCTIONS.md file
-            module_path = Path(__file__).parent.parent
-            instructions_path = module_path / "agents" / "INSTRUCTIONS.md"
+            # Determine the user's project directory
+            if 'CLAUDE_MPM_USER_PWD' in os.environ:
+                project_dir = Path(os.environ['CLAUDE_MPM_USER_PWD'])
+            else:
+                project_dir = Path.cwd()
+            
+            # Check for project-specific INSTRUCTIONS.md first
+            project_instructions_path = project_dir / ".claude-mpm" / "agents" / "INSTRUCTIONS.md"
+            
+            instructions_path = None
+            instructions_source = None
             
-            if not instructions_path.exists():
-                self.logger.warning(f"System instructions not found: {instructions_path}")
-                return None
+            if project_instructions_path.exists():
+                instructions_path = project_instructions_path
+                instructions_source = "PROJECT"
+                self.logger.info(f"Found project-specific INSTRUCTIONS.md: {instructions_path}")
+            else:
+                # Fall back to framework instructions
+                module_path = Path(__file__).parent.parent
+                framework_instructions_path = module_path / "agents" / "INSTRUCTIONS.md"
+                
+                if framework_instructions_path.exists():
+                    instructions_path = framework_instructions_path
+                    instructions_source = "FRAMEWORK"
+                    self.logger.info(f"Using framework INSTRUCTIONS.md: {instructions_path}")
+                else:
+                    self.logger.warning(f"No INSTRUCTIONS.md found in project or framework")
+                    return None
             
             # Read raw instructions
             raw_instructions = instructions_path.read_text()
@@ -1083,13 +1142,15 @@ class ClaudeRunner:
                 from claude_mpm.services.framework_claude_md_generator.content_assembler import ContentAssembler
                 assembler = ContentAssembler()
                 processed_instructions = assembler.apply_template_variables(raw_instructions)
-                self.logger.info("Loaded and processed PM framework system instructions with dynamic capabilities")
+                self.logger.info(f"Loaded and processed {instructions_source} PM instructions with dynamic capabilities")
                 return processed_instructions
             except ImportError:
                 self.logger.warning("ContentAssembler not available, using raw instructions")
+                self.logger.info(f"Loaded {instructions_source} PM instructions (raw)")
                 return raw_instructions
             except Exception as e:
                 self.logger.warning(f"Failed to process template variables: {e}, using raw instructions")
+                self.logger.info(f"Loaded {instructions_source} PM instructions (raw, processing failed)")
                 return raw_instructions
             
         except Exception as e:

claude_mpm/core/config_paths.py

@@ -35,7 +35,6 @@ class ConfigPaths:
     RESPONSES_DIR = "responses"
     
     # Agent subdirectories
-    AGENT_PROJECT_SPECIFIC = "project-specific"
     AGENT_USER_AGENTS = "user-agents"
     AGENT_USER_DEFINED = "user-defined"
     AGENT_SYSTEM = "templates"

claude_mpm/core/factories.py

@@ -57,14 +57,20 @@ class AgentServiceFactory(ServiceFactory):
         config = container.resolve(Config)
         
         # Get directories from config if not provided
+        import os
+        
         if framework_dir is None:
             framework_dir = Path(config.get('framework.dir', 'framework'))
             
         if project_dir is None:
-            project_dir = Path(config.get('project.dir', '.'))
+            # Check for user working directory from environment
+            if 'CLAUDE_MPM_USER_PWD' in os.environ:
+                project_dir = Path(os.environ['CLAUDE_MPM_USER_PWD'])
+            else:
+                project_dir = Path(config.get('project.dir', '.'))
             
-        # Create service with dependencies
-        service = AgentDeploymentService()
+        # Create service with proper working directory
+        service = AgentDeploymentService(working_directory=project_dir)
         
         # Inject any required dependencies
         if hasattr(service, 'set_directories'):

claude_mpm/dashboard/.claude-mpm/memories/README.md

@@ -0,0 +1,36 @@
+# Agent Memory System
+
+## Purpose
+Each agent maintains project-specific knowledge in these files. Agents read their memory file before tasks and update it when they learn something new.
+
+## Manual Editing
+Feel free to edit these files to:
+- Add project-specific guidelines
+- Remove outdated information  
+- Reorganize for better clarity
+- Add domain-specific knowledge
+
+## Memory Limits
+- Max file size: 8KB (~2000 tokens)
+- Max sections: 10
+- Max items per section: 15
+- Files auto-truncate when limits exceeded
+
+## File Format
+Standard markdown with structured sections. Agents expect:
+- Project Architecture
+- Implementation Guidelines
+- Common Mistakes to Avoid
+- Current Technical Context
+
+## How It Works
+1. Agents read their memory file before starting tasks
+2. Agents add learnings during or after task completion
+3. Files automatically enforce size limits
+4. Developers can manually edit for accuracy
+
+## Memory File Lifecycle
+- Created automatically when agent first runs
+- Updated through hook system after delegations
+- Manually editable by developers
+- Version controlled with project

claude_mpm/dashboard/README.md

@@ -0,0 +1,121 @@
+# Claude MPM Web Dashboard
+
+This directory contains the modular web dashboard for Claude MPM monitoring and management.
+
+## Structure
+
+```
+src/claude_mpm/dashboard/
+├── static/
+│   ├── css/
+│   │   └── dashboard.css          # Main stylesheet
+│   └── js/
+│       ├── socket-client.js       # Socket.IO connection management
+│       ├── dashboard.js          # Main dashboard application
+│       └── components/
+│           ├── event-viewer.js    # Event display and filtering
+│           ├── module-viewer.js   # Event detail viewer
+│           └── session-manager.js # Session management
+├── templates/
+│   └── index.html               # Main dashboard HTML
+├── index.html                   # Root index with redirect
+├── test_dashboard.html          # Test version for verification
+└── README.md                    # This file
+```
+
+## Components
+
+### SocketClient (`socket-client.js`)
+- Manages WebSocket connections to the Claude MPM server
+- Handles event reception and processing
+- Provides callbacks for connection state changes
+- Maintains event history and session tracking
+
+### EventViewer (`components/event-viewer.js`)
+- Displays events in a filterable list
+- Supports search, type filtering, and session filtering
+- Handles event selection and keyboard navigation
+- Updates metrics display (total events, events per minute, etc.)
+
+### ModuleViewer (`components/module-viewer.js`)
+- Shows detailed information about selected events
+- Provides structured views for different event types
+- Displays raw JSON data for debugging
+- Organizes events by class/category
+
+### SessionManager (`components/session-manager.js`)
+- Manages session selection and filtering
+- Updates session dropdown with available sessions
+- Tracks current active session
+- Updates footer information
+
+### Dashboard (`dashboard.js`)
+- Main application coordinator
+- Handles tab switching between Events, Agents, Tools, and Files
+- Manages component interactions
+- Provides global functions for backward compatibility
+
+## Features
+
+### File-Centric Files Tab
+The Files tab now shows a file-centric view where:
+- Each file appears only once in the list
+- Files show read/write icons based on operations performed
+- Most recently accessed files appear at the bottom
+- Clicking a file shows all operations performed on it with timestamps and agent information
+
+### Tab Organization
+- **Events**: All events with filtering and search
+- **Agents**: Agent-specific events and operations
+- **Tools**: Tool usage and parameters
+- **Files**: File operations organized by file path
+
+### Enhanced Event Details
+- Structured views for different event types
+- Todo checklists with status indicators
+- Agent and tool information
+- Session tracking and filtering
+
+## Usage
+
+### Development
+For development and testing, use `test_dashboard.html` which includes module verification.
+
+### Production
+Use `templates/dashboard.html` as the main template, ensuring all static files are served correctly.
+
+### Integration
+The dashboard can be integrated into a Flask/FastAPI application by serving the static files and using the template.
+
+## Migration from Original
+
+The original monolithic `claude_mpm_socketio_dashboard.html` has been replaced with a modular structure:
+
+1. **CSS**: Extracted to `static/css/dashboard.css`
+2. **JavaScript**: Split into logical modules in `static/js/`
+3. **HTML**: Clean template in `templates/dashboard.html`
+
+All original functionality has been preserved while improving:
+- Code organization and maintainability
+- Module reusability
+- Easier debugging and development
+- Better separation of concerns
+
+## Backward Compatibility
+
+Global functions are maintained for compatibility:
+- `connectSocket()`
+- `disconnectSocket()`
+- `clearEvents()`
+- `exportEvents()`
+- `clearSelection()`
+- `switchTab(tabName)`
+
+## Browser Support
+
+Requires modern browsers with support for:
+- ES6 Classes
+- Fetch API
+- Custom Events
+- CSS Grid/Flexbox
+- Socket.IO 4.x