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

claude_mpm/dashboard/templates/.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/templates/.claude-mpm/memories/engineer_agent.md

@@ -0,0 +1,39 @@
+# Engineer Agent Memory - templates
+
+<!-- MEMORY LIMITS: 8KB max | 10 sections max | 15 items per section -->
+<!-- Last Updated: 2025-08-07 18:26:34 | Auto-updated by: engineer -->
+
+## Project Context
+templates: mixed standard application
+
+## Project Architecture
+- Standard Application with mixed implementation
+
+## Coding Patterns Learned
+<!-- Items will be added as knowledge accumulates -->
+
+## Implementation Guidelines
+<!-- Items will be added as knowledge accumulates -->
+
+## Domain-Specific Knowledge
+<!-- Agent-specific knowledge for templates domain -->
+- Key project terms: templates
+- Focus on implementation patterns, coding standards, and best practices
+
+## Effective Strategies
+<!-- Successful approaches discovered through experience -->
+
+## Common Mistakes to Avoid
+<!-- Items will be added as knowledge accumulates -->
+
+## Integration Points
+<!-- Items will be added as knowledge accumulates -->
+
+## Performance Considerations
+<!-- Items will be added as knowledge accumulates -->
+
+## Current Technical Context
+<!-- Items will be added as knowledge accumulates -->
+
+## Recent Learnings
+<!-- Most recent discoveries and insights -->

claude_mpm/dashboard/templates/.claude-mpm/memories/version_control_agent.md

@@ -0,0 +1,38 @@
+# Version Control Agent Memory - templates
+
+<!-- MEMORY LIMITS: 8KB max | 10 sections max | 15 items per section -->
+<!-- Last Updated: 2025-08-07 18:28:51 | Auto-updated by: version_control -->
+
+## Project Context
+templates: mixed standard application
+
+## Project Architecture
+- Standard Application with mixed implementation
+
+## Coding Patterns Learned
+<!-- Items will be added as knowledge accumulates -->
+
+## Implementation Guidelines
+<!-- Items will be added as knowledge accumulates -->
+
+## Domain-Specific Knowledge
+<!-- Agent-specific knowledge for templates domain -->
+- Key project terms: templates
+
+## Effective Strategies
+<!-- Successful approaches discovered through experience -->
+
+## Common Mistakes to Avoid
+<!-- Items will be added as knowledge accumulates -->
+
+## Integration Points
+<!-- Items will be added as knowledge accumulates -->
+
+## Performance Considerations
+<!-- Items will be added as knowledge accumulates -->
+
+## Current Technical Context
+<!-- Items will be added as knowledge accumulates -->
+
+## Recent Learnings
+<!-- Most recent discoveries and insights -->

claude_mpm/hooks/README.md

@@ -0,0 +1,96 @@
+# Claude Code Hooks System
+
+This directory contains the Claude Code hook integration for claude-mpm.
+
+## Overview
+
+The hook system allows claude-mpm to intercept and handle commands typed in Claude Code, particularly the `/mpm` commands.
+
+## Structure
+
+```
+hooks/
+└── claude_hooks/              # Claude Code hook implementation
+    ├── hook_handler.py       # Main Python handler that processes events
+    └── hook_wrapper.sh       # Shell wrapper script (this is what gets installed in ~/.claude/settings.json)
+```
+
+## Claude Code Hooks
+
+The Claude Code hooks are the primary integration point between claude-mpm and Claude Code. They allow:
+
+- Intercepting `/mpm` commands before they reach the LLM
+- Providing custom responses and actions
+- Blocking LLM processing when appropriate
+
+### Installation
+
+To install the Claude Code hooks:
+
+```bash
+python scripts/install_hooks.py
+```
+
+This will:
+1. Create/update `~/.claude/settings.json` with hook configuration
+2. Point to the `hook_wrapper.sh` script
+3. Copy any custom commands to `~/.claude/commands/`
+
+### How It Works
+
+1. When you type in Claude Code, it triggers hook events
+2. Claude Code calls `hook_wrapper.sh` (the path in `~/.claude/settings.json`)
+3. The wrapper script:
+   - Detects if it's running from a local dev environment, npm, or PyPI installation
+   - Activates the appropriate Python environment
+   - Runs `hook_handler.py` with the event data
+4. The handler processes various event types:
+   - **UserPromptSubmit**: Checks if the prompt starts with `/mpm` and handles commands
+   - **PreToolUse**: Logs tool usage before execution
+   - **PostToolUse**: Logs tool results after execution
+   - **Stop**: Logs when a session or task stops
+   - **SubagentStop**: Logs when a subagent completes with agent type and ID
+5. For `/mpm` commands, it returns exit code 2 to block LLM processing
+6. All events are logged to project-specific log files in `.claude-mpm/logs/`
+
+### Available Commands
+
+- `/mpm` - Show help and available commands
+- `/mpm status` - Show claude-mpm status and environment
+- `/mpm help` - Show detailed help
+
+### Debugging
+
+To enable debug logging for hooks:
+
+```bash
+export CLAUDE_MPM_LOG_LEVEL=DEBUG
+```
+
+Then run Claude Code from that terminal. Hook events will be logged to `~/.claude-mpm/logs/`.
+
+## Legacy Hook System (Removed)
+
+The `builtin/` directory that contained the old internal hook system has been removed. All hook functionality is now handled through the Claude Code hooks system.
+
+## Development
+
+To add new `/mpm` commands:
+
+1. Edit `hook_handler.py` to handle the new command
+2. Update the help text in the `handle_mpm_help()` function
+3. Test by running Claude Code with the new command
+
+## Exit Codes
+
+The hook system uses specific exit codes:
+
+- `0` - Success, continue normal processing
+- `2` - Block LLM processing (command was handled)
+- Other - Error occurred
+
+## Environment Variables
+
+- `CLAUDE_MPM_LOG_LEVEL` - Set to DEBUG for detailed logging
+- `HOOK_EVENT_TYPE` - Set by Claude Code (UserPromptSubmit, PreToolUse, PostToolUse)
+- `HOOK_DATA` - JSON data from Claude Code with event details

claude_mpm/init.py

@@ -68,8 +68,7 @@ class ProjectInitializer:
         
         Creates:
         - .claude-mpm/
-          - agents/
-            - project-specific/
+          - agents/     (for project agent JSON files)
           - config/
           - responses/
           - logs/
@@ -80,20 +79,33 @@ class ProjectInitializer:
                 project_root = project_path
                 self.project_dir = project_path / ".claude-mpm"
             else:
-                # Always use current working directory for project directories
-                # This ensures .claude-mpm is created where the user launches the tool
-                project_root = Path.cwd()
+                # Check for the user's original working directory from launch script
+                # The launch script sets CLAUDE_MPM_USER_PWD before changing to framework directory
+                user_pwd = os.environ.get('CLAUDE_MPM_USER_PWD')
+                
+                if user_pwd:
+                    # Use the original user working directory
+                    project_root = Path(user_pwd)
+                    self.logger.debug(f"Using user working directory from CLAUDE_MPM_USER_PWD: {project_root}")
+                else:
+                    # Fallback to current working directory (backward compatibility)
+                    project_root = Path.cwd()
+                    self.logger.debug(f"CLAUDE_MPM_USER_PWD not set, using cwd: {project_root}")
+                
                 self.project_dir = project_root / ".claude-mpm"
             
             # Check if directory already exists
             directory_existed = self.project_dir.exists()
             
+            # Migrate existing agents from project-specific subdirectory if needed
+            self._migrate_project_agents()
+            
             # Create project directory
             self.project_dir.mkdir(exist_ok=True)
             
             # Create subdirectories
             directories = [
-                self.project_dir / "agents" / "project-specific",
+                self.project_dir / "agents",  # Direct agents directory for project agents
                 self.project_dir / "config",
                 self.project_dir / "responses",
                 self.project_dir / "logs",
@@ -122,6 +134,12 @@ class ProjectInitializer:
             else:
                 print(f"✓ Initialized .claude-mpm/ in {project_root}")
             
+            # Check if migration happened
+            agents_dir = self.project_dir / "agents"
+            if agents_dir.exists() and any(agents_dir.glob("*.json")):
+                agent_count = len(list(agents_dir.glob("*.json")))
+                print(f"✓ Found {agent_count} project agent(s) in .claude-mpm/agents/")
+            
             return True
             
         except Exception as e:
@@ -129,6 +147,54 @@ class ProjectInitializer:
             print(f"✗ Failed to create .claude-mpm/ directory: {e}")
             return False
     
+    def _migrate_project_agents(self):
+        """Migrate agents from old subdirectory structure to direct agents directory.
+        
+        WHY: We're simplifying the directory structure to match the deployment expectations.
+        The old structure had a subdirectory but the deployment now looks for agents 
+        directly in .claude-mpm/agents/.
+        """
+        if not self.project_dir:
+            return
+        
+        old_agents_dir = self.project_dir / "agents" / "project-specific"
+        new_agents_dir = self.project_dir / "agents"
+        
+        # Check if old directory exists with JSON files
+        if old_agents_dir.exists() and old_agents_dir.is_dir():
+            json_files = list(old_agents_dir.glob("*.json"))
+            if json_files:
+                self.logger.info(f"Migrating {len(json_files)} agents from old subdirectory")
+                
+                # Ensure new agents directory exists
+                new_agents_dir.mkdir(parents=True, exist_ok=True)
+                
+                # Move each JSON file
+                migrated_count = 0
+                for json_file in json_files:
+                    try:
+                        target_file = new_agents_dir / json_file.name
+                        if not target_file.exists():
+                            # Move the file
+                            shutil.move(str(json_file), str(target_file))
+                            migrated_count += 1
+                            self.logger.debug(f"Migrated {json_file.name} to agents directory")
+                        else:
+                            self.logger.debug(f"Skipping {json_file.name} - already exists in target")
+                    except Exception as e:
+                        self.logger.error(f"Failed to migrate {json_file.name}: {e}")
+                
+                if migrated_count > 0:
+                    print(f"✓ Migrated {migrated_count} agent(s) from old location to agents/")
+                
+                # Remove old directory if empty
+                try:
+                    if not any(old_agents_dir.iterdir()):
+                        old_agents_dir.rmdir()
+                        self.logger.debug("Removed empty old subdirectory")
+                except Exception as e:
+                    self.logger.debug(f"Could not remove old directory: {e}")
+    
     def _find_project_root(self) -> Optional[Path]:
         """Find project root by looking for .git or other project markers."""
         current = Path.cwd()
@@ -237,19 +303,23 @@ class ProjectInitializer:
         
         Shows clear information about where directories are being created.
         """
-        # Show working directory info at startup
-        cwd = Path.cwd()
-        framework_path = Path(__file__).parent.parent.parent
+        # Determine actual working directory
+        user_pwd = os.environ.get('CLAUDE_MPM_USER_PWD')
+        if user_pwd:
+            actual_wd = Path(user_pwd)
+            self.logger.info(f"User working directory (from CLAUDE_MPM_USER_PWD): {actual_wd}")
+        else:
+            actual_wd = Path.cwd()
+            self.logger.info(f"Working directory: {actual_wd}")
         
-        # Log startup context
-        self.logger.info(f"Working directory: {cwd}")
+        framework_path = Path(__file__).parent.parent.parent
         self.logger.info(f"Framework path: {framework_path}")
         
         # Initialize user directory (in home)
         user_ok = self.initialize_user_directory()
         
-        # Initialize project directory (in current working directory)
-        self.logger.info(f"Checking for .claude-mpm/ in {cwd}")
+        # Initialize project directory (in user's actual working directory)
+        self.logger.info(f"Checking for .claude-mpm/ in {actual_wd}")
         project_ok = self.initialize_project_directory()
         
         return user_ok and project_ok