claude-mpm 4.0.25

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Claude MPM Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,192 @@
+# Claude MPM - Multi-Agent Project Manager
+
+A powerful orchestration framework for Claude Code that enables multi-agent workflows, session management, and real-time monitoring through an intuitive interface.
+
+> **Quick Start**: See [QUICKSTART.md](QUICKSTART.md) to get running in 5 minutes!
+
+## Features
+
+- 🤖 **Multi-Agent System**: 15 specialized agents for comprehensive project management
+- 🧠 **Agent Memory System**: Persistent learning with project-specific knowledge retention
+- 🔄 **Session Management**: Resume previous sessions with `--resume` 
+- 📊 **Real-Time Monitoring**: Live dashboard with `--monitor` flag
+- 🔌 **MCP Gateway**: Model Context Protocol integration for extensible tool capabilities
+- 📁 **Multi-Project Support**: Per-session working directories
+- 🔍 **Git Integration**: View diffs and track changes across projects
+- 🎯 **Smart Task Orchestration**: PM agent intelligently routes work to specialists
+- ⚡ **50-80% Performance Improvement**: Through intelligent caching and lazy loading
+- 🔒 **Enhanced Security**: Comprehensive input validation and sanitization framework
+
+## Quick Installation
+
+```bash
+pip install claude-mpm
+```
+
+**That's it!** See [QUICKSTART.md](QUICKSTART.md) for immediate usage or [docs/user/installation.md](docs/user/installation.md) for advanced options.
+
+## Quick Usage
+
+```bash
+# Start interactive mode (recommended)
+claude-mpm
+
+# Start with monitoring dashboard
+claude-mpm run --monitor
+
+# Use MCP Gateway for external tool integration
+claude-mpm mcp
+
+# Manage memory for large conversation histories
+claude-mpm cleanup-memory
+```
+
+See [QUICKSTART.md](QUICKSTART.md) for complete usage examples.
+
+
+## Architecture (v3.8.2+)
+
+Following the TSK-0053 refactoring, Claude MPM features:
+
+- **Service-Oriented Architecture**: Five specialized service domains
+- **Interface-Based Contracts**: All services implement explicit interfaces
+- **Dependency Injection**: Service container with automatic resolution
+- **50-80% Performance Improvement**: Through lazy loading and intelligent caching
+- **Enhanced Security**: Comprehensive input validation and sanitization framework
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed architecture information.
+
+## Key Capabilities
+
+### Multi-Agent Orchestration
+
+Claude MPM includes 15 specialized agents:
+
+#### Core Development
+- **Engineer** - Software development and implementation
+- **Research** - Code analysis and research  
+- **Documentation** - Documentation creation and maintenance
+- **QA** - Testing and quality assurance
+- **Security** - Security analysis and implementation
+
+#### Operations & Infrastructure
+- **Ops** - Operations and deployment
+- **Version Control** - Git and version management
+- **Data Engineer** - Data pipeline and ETL development
+
+#### Web Development
+- **Web UI** - Frontend and UI development
+- **Web QA** - Web testing and E2E validation
+
+#### Project Management
+- **Ticketing** - Issue tracking and management
+- **Project Organizer** - File organization and structure
+- **Memory Manager** - Project memory and context management
+
+#### Code Quality
+- **Refactoring Engineer** - Code refactoring and optimization
+- **Code Analyzer** - Static code analysis with AST and tree-sitter
+
+### Agent Memory System
+Agents learn project-specific patterns and remember insights across sessions. Initialize with `claude-mpm memory init`.
+
+### MCP Gateway (Model Context Protocol)
+
+Claude MPM includes a powerful MCP Gateway that enables:
+- Integration with external tools and services
+- Custom tool development
+- Protocol-based communication
+- Extensible architecture
+
+See [MCP Gateway Documentation](docs/developer/13-mcp-gateway/README.md) for details.
+
+### Memory Management
+
+Large conversation histories can consume 2GB+ of memory. Use the `cleanup-memory` command to manage Claude conversation history:
+
+```bash
+# Clean up old conversation history
+claude-mpm cleanup-memory
+
+# Keep only recent conversations
+claude-mpm cleanup-memory --days 7
+```
+
+### Real-Time Monitoring
+The `--monitor` flag opens a web dashboard showing live agent activity, file operations, and session management.
+
+See [docs/MEMORY.md](docs/MEMORY.md) and [docs/developer/11-dashboard/README.md](docs/developer/11-dashboard/README.md) for details.
+
+
+## Documentation
+
+### User Documentation
+- **[Quick Start Guide](QUICKSTART.md)** - Get running in 5 minutes
+- **[Installation Guide](docs/user/installation.md)** - Complete installation options
+- **[User Guide](docs/user/)** - Detailed usage documentation
+- **[Memory System](docs/MEMORY.md)** - Agent memory documentation
+- **[Troubleshooting](docs/user/troubleshooting.md)** - Common issues and solutions
+
+### Developer Documentation
+- **[Architecture Overview](docs/ARCHITECTURE.md)** - Service-oriented architecture and design
+- **[API Reference](docs/api/)** - Complete API documentation with Sphinx
+- **[Service Layer Guide](docs/developer/SERVICES.md)** - Service interfaces and implementations
+- **[MCP Gateway Guide](docs/developer/13-mcp-gateway/README.md)** - Model Context Protocol integration
+- **[Performance Guide](docs/PERFORMANCE.md)** - Optimization and caching strategies
+- **[Security Guide](docs/SECURITY.md)** - Security framework and best practices
+- **[Testing Guide](docs/TESTING.md)** - Testing patterns and strategies
+- **[Migration Guide](docs/MIGRATION.md)** - Upgrading from previous versions
+- **[Developer Guide](docs/developer/)** - Comprehensive development documentation
+
+### API Documentation
+Comprehensive API documentation is available at [docs/api/](docs/api/) - build with `make html` in that directory.
+
+## Recent Updates (v3.8.2)
+
+**Major Architecture Refactoring (TSK-0053)**: Complete service-oriented redesign with 50-80% performance improvements, enhanced security, and interface-based design.
+
+**Process Management Improvements**: Enhanced hook system reliability with automatic process cleanup, timeout protection, and orphan process monitoring to prevent resource leaks.
+
+See [CHANGELOG.md](CHANGELOG.md) for full history and [docs/MIGRATION.md](docs/MIGRATION.md) for upgrade instructions.
+
+## Development
+
+### Quick Development Setup
+```bash
+# Complete development setup with code formatting and quality tools
+make dev-complete
+
+# Or step by step:
+make setup-dev          # Install in development mode
+make setup-pre-commit    # Set up automated code formatting
+```
+
+### Code Quality & Formatting
+The project uses automated code formatting and quality checks:
+- **Black** for code formatting
+- **isort** for import sorting
+- **flake8** for linting
+- **mypy** for type checking
+- **Pre-commit hooks** for automatic enforcement
+
+See [docs/developer/CODE_FORMATTING.md](docs/developer/CODE_FORMATTING.md) for details.
+
+### Contributing
+Contributions are welcome! Please see our [project structure guide](docs/STRUCTURE.md) and follow the established patterns.
+
+**Development Workflow**:
+1. Run `make dev-complete` to set up your environment
+2. Code formatting happens automatically on commit
+3. All code must pass quality checks before merging
+
+### Project Structure
+See [docs/STRUCTURE.md](docs/STRUCTURE.md) for codebase organization.
+
+### License
+MIT License - see [LICENSE](LICENSE) file.
+
+## Credits
+
+- Based on [claude-multiagent-pm](https://github.com/kfsone/claude-multiagent-pm)
+- Enhanced for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) integration
+- Built with ❤️ by the Claude MPM community

package/README.npm.md

@@ -0,0 +1,71 @@
+# Claude MPM (npm wrapper)
+
+This is the npm wrapper for the **Claude Multi-Agent Project Manager (claude-mpm)**, a Python framework that extends Claude Desktop with multi-agent orchestration capabilities.
+
+## Requirements
+
+- **Node.js** 14.0.0 or later
+- **Python** 3.8 or later
+- **macOS** or **Linux** (Windows support via WSL)
+
+## Installation
+
+```bash
+npm install -g @bobmatnyc/claude-mpm
+```
+
+## Usage
+
+Once installed, you can use the `claude-mpm` command directly:
+
+```bash
+# Initialize claude-mpm
+claude-mpm config init
+
+# Deploy agents
+claude-mpm agents deploy
+
+# Run with an agent
+claude-mpm run --agent engineer
+
+# View version info
+claude-mpm info
+```
+
+## What this package does
+
+This npm package is a wrapper that:
+
+1. **Detects Python 3.8+** on your system
+2. **Automatically installs** the `claude-mpm` Python package 
+3. **Launches the Python CLI** with your arguments
+
+## Python Package
+
+The actual claude-mpm functionality is provided by the Python package. If you prefer to install directly with Python:
+
+```bash
+pip install claude-mpm
+```
+
+## Features
+
+- **Multi-Agent Orchestration**: Coordinate specialized AI agents for different tasks
+- **Ticket Management**: Integrated ticketing system with aitrackdown
+- **Memory System**: Persistent agent memory and context management
+- **WebSocket Dashboard**: Real-time monitoring of agent activities
+- **MCP Gateway**: Model Context Protocol server integration
+- **Claude Desktop Integration**: Seamless integration with Anthropic's Claude Desktop
+
+## Documentation
+
+For detailed documentation, visit the [main repository](https://github.com/bobmatnyc/claude-mpm).
+
+## License
+
+MIT - see [LICENSE](LICENSE) file.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/bobmatnyc/claude-mpm/issues)
+- **Repository**: [GitHub](https://github.com/bobmatnyc/claude-mpm)

package/npm-bin/claude-mpm.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+/**
+ * Claude MPM npm wrapper
+ * This wrapper ensures Python 3.8+ is available and launches the claude-mpm Python package
+ */
+
+const { execSync, spawn } = require('child_process');
+const { existsSync } = require('fs');
+const path = require('path');
+
+const REQUIRED_PYTHON_VERSION = [3, 8];
+
+function checkPythonVersion(pythonCmd) {
+    try {
+        const versionOutput = execSync(`${pythonCmd} --version`, { encoding: 'utf8', stdio: 'pipe' });
+        const versionMatch = versionOutput.match(/Python (\d+)\.(\d+)\.(\d+)/);
+        
+        if (!versionMatch) return false;
+        
+        const [, major, minor] = versionMatch.map(Number);
+        return major > REQUIRED_PYTHON_VERSION[0] || 
+               (major === REQUIRED_PYTHON_VERSION[0] && minor >= REQUIRED_PYTHON_VERSION[1]);
+    } catch (error) {
+        return false;
+    }
+}
+
+function findPython() {
+    const pythonCommands = ['python3', 'python', 'python3.11', 'python3.10', 'python3.9', 'python3.8'];
+    
+    for (const cmd of pythonCommands) {
+        if (checkPythonVersion(cmd)) {
+            return cmd;
+        }
+    }
+    return null;
+}
+
+function main() {
+    const pythonCmd = findPython();
+    
+    if (!pythonCmd) {
+        console.error(`
+❌ Error: Python ${REQUIRED_PYTHON_VERSION.join('.')}+ is required but not found.
+
+Please install Python ${REQUIRED_PYTHON_VERSION.join('.')} or later and try again.
+You can download Python from: https://www.python.org/downloads/
+
+Alternatively, install claude-mpm directly with pip:
+  pip install claude-mpm
+`);
+        process.exit(1);
+    }
+
+    // Check if claude-mpm is already installed
+    try {
+        execSync(`${pythonCmd} -c "import claude_mpm"`, { stdio: 'pipe' });
+    } catch (error) {
+        console.log('📦 Installing claude-mpm Python package...');
+        try {
+            execSync(`${pythonCmd} -m pip install claude-mpm`, { stdio: 'inherit' });
+            console.log('✅ claude-mpm installed successfully!');
+        } catch (installError) {
+            console.error(`
+❌ Failed to install claude-mpm Python package.
+
+Please install it manually:
+  ${pythonCmd} -m pip install claude-mpm
+
+Or using pip directly:
+  pip install claude-mpm
+`);
+            process.exit(1);
+        }
+    }
+
+    // Launch claude-mpm with all arguments
+    const args = process.argv.slice(2);
+    const child = spawn(pythonCmd, ['-m', 'claude_mpm'].concat(args), { 
+        stdio: 'inherit',
+        env: process.env 
+    });
+
+    child.on('exit', (code) => {
+        process.exit(code || 0);
+    });
+
+    child.on('error', (error) => {
+        console.error(`❌ Error launching claude-mpm: ${error.message}`);
+        process.exit(1);
+    });
+}
+
+if (require.main === module) {
+    main();
+}
+
+module.exports = { main, findPython, checkPythonVersion };

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "claude-mpm",
+  "version": "4.0.25",
+  "description": "NPM wrapper for claude-mpm Python package - Requires Python 3.8+. Orchestrate Claude with agent delegation and ticket tracking",
+  "keywords": [
+    "claude",
+    "ai",
+    "orchestration",
+    "multi-agent",
+    "project-management",
+    "cli",
+    "claude-code",
+    "anthropic"
+  ],
+  "homepage": "https://github.com/bobmatnyc/claude-mpm",
+  "bugs": {
+    "url": "https://github.com/bobmatnyc/claude-mpm/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bobmatnyc/claude-mpm.git"
+  },
+  "license": "MIT",
+  "author": "Bob Matsuoka <bob@matsuoka.com>",
+  "bin": {
+    "claude-mpm": "npm-bin/claude-mpm.js"
+  },
+  "files": [
+    "npm-bin/",
+    "README.npm.md",
+    "LICENSE",
+    "scripts/postinstall.js"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "build:dashboard": "vite build && python -c \"import shutil; shutil.copytree('src/claude_mpm/dashboard/static/dist', 'src/claude_mpm/dashboard/static/built', dirs_exist_ok=True)\"",
+    "clean": "rm -rf src/claude_mpm/dashboard/static/dist src/claude_mpm/dashboard/static/built"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "preferGlobal": true,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "vite": "^5.0.0",
+    "terser": "^5.24.0"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+/**
+ * Post-install script for @bobmatnyc/claude-mpm npm package
+ *
+ * This is a wrapper that will install the Python package on first run
+ */
+
+console.log('\n🎉 @bobmatnyc/claude-mpm npm wrapper installed!');
+console.log('\n⚠️  IMPORTANT: This is an npm wrapper for a Python package');
+console.log('   The actual claude-mpm implementation requires Python 3.8+\n');
+
+console.log('📋 Requirements:');
+console.log('  • Python 3.8 or later');
+console.log('  • Claude Code 1.0.60 or later');
+console.log('  • UV, pip, or pipx for Python package management\n');
+
+console.log('🚀 Installation Options:');
+console.log('  1. UV (recommended): uv pip install claude-mpm');
+console.log('  2. pip: pip install claude-mpm');
+console.log('  3. pipx: pipx install claude-mpm\n');
+
+console.log('📦 What happens on first run:');
+console.log('  • If claude-mpm Python package is not found, this wrapper will:');
+console.log('    - Attempt to install it automatically using pip or pipx');
+console.log('    - Guide you through any installation issues\n');
+
+console.log('📖 For complete installation guide: https://github.com/bobmatnyc/claude-mpm#installation\n');
+
+// Quick checks (non-blocking)
+const { execSync } = require('child_process');
+
+let pythonFound = false;
+let pythonPath = null;
+let pythonVersion = null;
+
+// Check for Python
+try {
+  pythonVersion = execSync('python3 --version 2>&1', { encoding: 'utf8' }).trim();
+  pythonPath = 'python3';
+  pythonFound = true;
+} catch (e) {
+  try {
+    pythonVersion = execSync('python --version 2>&1', { encoding: 'utf8' }).trim();
+    pythonPath = 'python';
+    pythonFound = true;
+  } catch (e2) {
+    // Python not found
+  }
+}
+
+if (pythonFound) {
+  // Extract version number
+  const versionMatch = pythonVersion.match(/Python (\d+\.\d+\.\d+)/);
+  if (versionMatch) {
+    const [major, minor] = versionMatch[1].split('.').map(Number);
+    if (major >= 3 && minor >= 8) {
+      console.log(`✅ Found ${pythonVersion}`);
+    } else {
+      console.warn(`⚠️  Found ${pythonVersion} but Python 3.8+ is required`);
+      console.warn('   Please upgrade Python from https://python.org');
+    }
+  }
+} else {
+  console.error('❌ Python not found!');
+  console.error('   Python 3.8+ is REQUIRED for claude-mpm to function');
+  console.error('   Please install Python from:');
+  console.error('   • https://python.org (official)');
+  console.error('   • brew install python3 (macOS)');
+  console.error('   • apt install python3 (Ubuntu/Debian)');
+}
+
+// Check for Claude CLI
+try {
+  const claudeVersion = execSync('claude --version 2>&1', { encoding: 'utf8' });
+  console.log(`✅ Found Claude Code ${claudeVersion.trim()}`);
+} catch (e) {
+  console.warn('⚠️  Claude Code not found');
+  console.warn('   Please install Claude Code 1.0.60+ from https://claude.ai/code');
+}
+
+// Check for Python package managers
+const packageManagers = [];
+try {
+  execSync('uv --version 2>&1', { encoding: 'utf8' });
+  packageManagers.push('UV');
+} catch (e) {}
+
+try {
+  execSync('pipx --version 2>&1', { encoding: 'utf8' });
+  packageManagers.push('pipx');
+} catch (e) {}
+
+try {
+  execSync('pip --version 2>&1', { encoding: 'utf8' });
+  packageManagers.push('pip');
+} catch (e) {}
+
+if (packageManagers.length > 0) {
+  console.log(`✅ Found Python package managers: ${packageManagers.join(', ')}`);
+} else if (pythonFound) {
+  console.warn('⚠️  No Python package managers found (UV, pip, or pipx)');
+  console.warn('   The wrapper will attempt to install pip on first run');
+}
+
+console.log('\n💡 Next step: Run "claude-mpm" to start using the tool');