claude-mpm 5.4.55__py3-none-any.whl → 5.4.85__py3-none-any.whl

claude_mpm/utils/agent_dependency_loader.py

@@ -65,6 +65,7 @@ class AgentDependencyLoader:
         self.deployment_state_file = (
             Path.cwd() / ".claude" / "agents" / ".mpm_deployment_state"
         )
+        self.is_uv_tool = self._check_uv_tool_installation()
 
     def discover_deployed_agents(self) -> Dict[str, Path]:
         """
@@ -191,9 +192,42 @@ class AgentDependencyLoader:
         logger.debug(f"Loaded dependencies for {len(agent_dependencies)} agents")
         return agent_dependencies
 
+    def _check_uv_tool_installation(self) -> bool:
+        """
+        Check if running in UV tool environment (no pip available).
+
+        WHY: UV tool environments don't have pip installed. The executable
+        path typically contains ".local/share/uv/tools/" and the UV_TOOL_DIR
+        environment variable is set. In such environments, we need to use
+        'uv pip' instead of 'python -m pip'.
+
+        Returns:
+            True if UV tool environment, False otherwise
+        """
+        import os
+
+        # Check UV_TOOL_DIR environment variable
+        uv_tool_dir = os.environ.get("UV_TOOL_DIR", "")
+        if uv_tool_dir and "claude-mpm" in uv_tool_dir:
+            logger.debug(f"UV tool environment detected via UV_TOOL_DIR: {uv_tool_dir}")
+            return True
+
+        # Check executable path for UV tool patterns
+        executable = sys.executable
+        if ".local/share/uv/tools/" in executable or "/uv/tools/" in executable:
+            logger.debug(
+                f"UV tool environment detected via executable path: {executable}"
+            )
+            return True
+
+        return False
+
     def check_python_dependency(self, package_spec: str) -> Tuple[bool, Optional[str]]:
         """
-        Check if a Python package dependency is satisfied.
+        Check if a Python package dependency is satisfied in the TARGET environment.
+
+        WHY: UV tool environments use a separate Python installation. We must check
+        packages in the same environment where they would be installed/used.
 
         Args:
             package_spec: Package specification (e.g., "pandas>=2.0.0")
@@ -221,7 +255,70 @@ class AgentDependencyLoader:
                 )
                 return True, "optional-skipped"
 
-            # Try to import and check version
+            # For UV tool environments, check via UV's Python
+            if self.is_uv_tool:
+                try:
+                    verify_cmd = [
+                        "uv",
+                        "run",
+                        "--no-project",
+                        "python",
+                        "-c",
+                        f"import importlib.metadata; print(importlib.metadata.version('{package_name}'))",
+                    ]
+                    result = subprocess.run(
+                        verify_cmd, capture_output=True, timeout=30, check=False
+                    )
+                    if result.returncode == 0:
+                        version = result.stdout.decode().strip()
+                        self.checked_packages.add(package_name)
+                        if req.specifier.contains(version):
+                            logger.debug(
+                                f"Package {package_name} {version} satisfied in UV environment"
+                            )
+                            return True, version
+                        logger.debug(
+                            f"{package_name} {version} does not satisfy {req.specifier}"
+                        )
+                        return False, version
+                    # Check alternatives for optional packages
+                    if package_name in self.OPTIONAL_DB_PACKAGES:
+                        for alternative in self.OPTIONAL_DB_PACKAGES[package_name]:
+                            alt_cmd = [
+                                "uv",
+                                "run",
+                                "--no-project",
+                                "python",
+                                "-c",
+                                f"import importlib.metadata; print(importlib.metadata.version('{alternative}'))",
+                            ]
+                            alt_result = subprocess.run(
+                                alt_cmd, capture_output=True, timeout=30, check=False
+                            )
+                            if alt_result.returncode == 0:
+                                alt_version = alt_result.stdout.decode().strip()
+                                logger.info(
+                                    f"Using {alternative} as alternative to {package_name}"
+                                )
+                                self.checked_packages.add(package_name)
+                                return True, f"{alternative}:{alt_version}"
+                        # If no alternatives work, mark as optional failure
+                        self.optional_failed[package_name] = "No alternatives available"
+                        logger.warning(
+                            f"Optional package {package_name} not found, marking as optional"
+                        )
+                        return True, "optional-not-found"
+                    return False, None
+                except subprocess.TimeoutExpired:
+                    logger.warning(f"Timeout checking {package_name} in UV environment")
+                    return False, None
+                except Exception as e:
+                    logger.debug(
+                        f"Error checking {package_name} in UV environment: {e}"
+                    )
+                    return False, None
+
+            # For normal Python, try to import and check version
             try:
                 import importlib.metadata
 
@@ -671,8 +768,10 @@ class AgentDependencyLoader:
                 )
 
                 if is_uv_tool:
-                    cmd = ["uv", "pip", "install"]
-                    logger.debug("Using 'uv pip install' for UV tool environment")
+                    cmd = ["uv", "pip", "install", "--python", sys.executable]
+                    logger.debug(
+                        f"Using 'uv pip install --python {sys.executable}' for UV tool environment"
+                    )
                 else:
                     cmd = [sys.executable, "-m", "pip", "install"]
 

claude_mpm/utils/robust_installer.py

@@ -332,10 +332,12 @@ class RobustPackageInstaller:
         Returns:
             Command as list of arguments
         """
-        # UV tool environments don't have pip; use uv pip instead
+        # UV tool environments don't have pip; use uv pip install --python instead
         if self.is_uv_tool:
-            base_cmd = ["uv", "pip", "install"]
-            logger.debug("Using 'uv pip install' for UV tool environment")
+            base_cmd = ["uv", "pip", "install", "--python", sys.executable]
+            logger.debug(
+                f"Using 'uv pip install --python {sys.executable}' for UV tool environment"
+            )
         else:
             base_cmd = [sys.executable, "-m", "pip", "install"]
 
@@ -478,42 +480,56 @@ class RobustPackageInstaller:
 
     def _verify_installation(self, package_spec: str) -> bool:
         """
-        Verify that a package was successfully installed.
+        Verify that a package was successfully installed in the TARGET environment.
+
+        WHY: UV installs packages to its own Python environment, not the current process.
+        We must verify in the same environment where packages were installed.
 
         Args:
             package_spec: Package specification
 
         Returns:
-            True if package is installed and importable
+            True if package is installed and importable in the target environment
         """
         package_name = self._extract_package_name(package_spec)
 
-        # Convert package name to import name (e.g., tree-sitter-ruby -> tree_sitter_ruby)
-        import_name = package_name.replace("-", "_")
-
         try:
-            # Check if package is installed
+            if self.is_uv_tool:
+                # For UV tool, verify via UV's Python environment
+                verify_cmd = [
+                    "uv",
+                    "run",
+                    "--no-project",
+                    "python",
+                    "-c",
+                    f"import importlib.metadata; print(importlib.metadata.version('{package_name}'))",
+                ]
+                result = subprocess.run(
+                    verify_cmd, capture_output=True, timeout=30, check=False
+                )
+                if result.returncode == 0:
+                    logger.debug(
+                        f"Package {package_name} verified in UV environment: {result.stdout.decode().strip()}"
+                    )
+                    return True
+                logger.debug(
+                    f"Package {package_name} not found in UV environment: {result.stderr.decode().strip()}"
+                )
+                return False
+            # For normal Python, use importlib.metadata in current process
             import importlib.metadata
 
             try:
                 version = importlib.metadata.version(package_name)
                 logger.debug(f"Package {package_name} version {version} is installed")
-
-                # For tree-sitter packages, don't try to import (they have C extensions)
-                if package_name.startswith("tree-sitter-"):
-                    return True
-
-                # Try to import the package
-                try:
-                    __import__(import_name)
-                    return True
-                except ImportError:
-                    # Some packages have different import names, that's OK
-                    return True
+                return True
 
             except importlib.metadata.PackageNotFoundError:
                 return False
 
+        except subprocess.TimeoutExpired:
+            logger.warning(f"Verification timeout for {package_name}")
+            return False
         except ImportError:
             # Fallback for older Python versions
             try:
@@ -523,6 +539,9 @@ class RobustPackageInstaller:
                 return True
             except pkg_resources.DistributionNotFound:
                 return False
+        except Exception as e:
+            logger.debug(f"Verification error for {package_name}: {e}")
+            return False
 
     def _is_retryable_error(self, error: Optional[str]) -> bool:
         """
@@ -687,10 +706,12 @@ class RobustPackageInstaller:
             Tuple of (success, error_message)
         """
         try:
-            # UV tool environments don't have pip; use uv pip instead
+            # UV tool environments don't have pip; use uv pip install --python instead
             if self.is_uv_tool:
-                cmd = ["uv", "pip", "install"]
-                logger.debug("Using 'uv pip install' for batch installation")
+                cmd = ["uv", "pip", "install", "--python", sys.executable]
+                logger.debug(
+                    f"Using 'uv pip install --python {sys.executable}' for batch installation"
+                )
             else:
                 cmd = [sys.executable, "-m", "pip", "install"]
 

{claude_mpm-5.4.55.dist-info → claude_mpm-5.4.85.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 5.4.55
+Version: 5.4.85
 Summary: Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking
 Author-email: Bob Matsuoka <bob@matsuoka.com>
 Maintainer: Claude MPM Team
@@ -116,7 +116,13 @@ A powerful orchestration framework for **Claude Code (CLI)** that enables multi-
 > - Minimum: v1.0.92 (hooks support)
 > - Recommended: v2.0.30+ (latest features)
 
-> **Quick Start**: See [docs/user/getting-started.md](docs/user/getting-started.md) to get running in 5 minutes!
+> **Quick Start**: See [docs/user/getting-started.md](docs/getting-started/README.md) to get running in 5 minutes!
+
+---
+
+> **🆕 NEW for Founders!** Not a software engineer? **[Start with our Absolute Beginner's Guide](docs/absolute-beginners-guide.md)** — designed specifically for non-technical founders and business leaders who want to understand and oversee their technical projects. No coding experience required!
+
+---
 
 ## 🚀 What's New in v5.0
 
@@ -153,13 +159,16 @@ claude-mpm agent-source list
 **Agents** (47+ agents):
 - 🏢 System: `bobmatnyc/claude-mpm-agents` - Core agent templates
 
-**Skills** (hundreds of skills):
-- 🏢 System: `bobmatnyc/claude-mpm-skills` - Community skills
-- 🎯 Official: `anthropics/skills` - Anthropic's official skills (14+ skills)
+**Skills** (17 bundled, optional external):
+- 📦 **Bundled**: 17 skills included in core installation (no external repo)
+- 🏢 **Optional**: `bobmatnyc/claude-mpm-skills` - Community skills (not enabled by default)
+- 🔧 **Custom**: Add your own via `~/.claude/skills/` or `.claude/skills/`
 
 **What This Means:**
-- ✅ **Automatic Setup**: Everything deploys on first run
-- ✅ **Always Updated**: Git repositories sync on startup
+- ✅ **Bundled Skills**: Work immediately, no external dependencies
+- ✅ **Offline Support**: Core skills work without internet
+- ✅ **Automatic Setup**: Agents deploy from Git on first run
+- ✅ **Always Updated**: Agent repositories sync on startup
 - ✅ **Nested Support**: Repositories with subdirectories are automatically flattened
 - ✅ **Template Inheritance**: BASE-AGENT.md files cascade from parent directories
 - ✅ **Priority System**: Control which sources win when multiple repos provide the same agent/skill
@@ -201,12 +210,13 @@ See [docs/features/hierarchical-base-agents.md](docs/features/hierarchical-base-
 
 ### 🎯 Skills System
 
-- **Hundreds of Skills**: Comprehensive skill library from curated repositories
-- **Official Skills**: 14+ skills from Anthropic's official repository
+- **17 Bundled Skills**: Production-ready skills included in core installation (no external repo required)
+- **Custom Skills**: Add your own project-specific or user-level skills locally
 - **Three-Tier Organization**: Bundled/user/project skills with priority resolution
 - **Auto-Linking**: Skills automatically linked to relevant agents
 - **Interactive Configuration**: Skills wizard via `claude-mpm configure`
 - **Version Tracking**: Semantic versioning for all skills
+- **Community Contributions**: Submit PRs to add skills to the bundled collection
 
 ### 🔌 Advanced Integration
 
@@ -230,7 +240,7 @@ See [docs/features/hierarchical-base-agents.md](docs/features/hierarchical-base-
 
 **Before installing Claude MPM**, ensure you have:
 
-1. **Python 3.11+** (required for kuzu-memory dependency)
+1. **Python 3.10+** (3.11+ recommended for optimal compatibility)
 2. **Claude Code CLI v1.0.92+** (required!)
 
 ```bash
@@ -243,19 +253,18 @@ claude --version
 
 ### Install Claude MPM
 
+Choose your preferred installation method:
+
+**Homebrew (macOS):**
 ```bash
 # Basic installation
-pip install claude-mpm
-
-# Or with uv (faster)
-uv tool install claude-mpm
+brew install claude-mpm
 
 # Install with monitoring dashboard (recommended)
-pip install "claude-mpm[monitor]"
-uv tool install "claude-mpm[monitor]"
+brew install claude-mpm --with-monitor
 ```
 
-Or with pipx/uvx (recommended for isolated installation):
+**pipx/uvx (recommended for isolated installation):**
 ```bash
 # Basic installation
 pipx install claude-mpm
@@ -271,6 +280,19 @@ pipx install "claude-mpm[monitor]"
 uv tool install "claude-mpm[monitor]"
 ```
 
+**pip/uv (system-wide installation):**
+```bash
+# Basic installation
+pip install claude-mpm
+
+# Or with uv (faster)
+uv tool install claude-mpm
+
+# Install with monitoring dashboard (recommended)
+pip install "claude-mpm[monitor]"
+uv tool install "claude-mpm[monitor]"
+```
+
 ### Verify Installation
 
 ```bash
@@ -283,21 +305,23 @@ claude-mpm doctor
 
 # Verify Git repositories are synced
 ls ~/.claude/agents/    # Should show 47+ agents
-ls ~/.claude/skills/    # Should show hundreds of skills
+
+# Bundled skills are in Python package (always available)
+# Custom skills go in ~/.claude/skills/ or .claude/skills/
 
 # Check agent sources
 claude-mpm agent-source list
 
-# Check skill sources
+# Check skill sources (only if you've added external sources)
 claude-mpm skill-source list
 ```
 
 **What You Should See:**
 - ✅ 47+ agents deployed to `~/.claude/agents/`
-- ✅ Hundreds of skills deployed to `~/.claude/skills/`
-- ✅ Two agent sources configured (system + official)
-- ✅ Two skill sources configured (system + official)
-- ✅ Progress bars showing sync and deployment phases
+- ✅ 17 bundled skills (in Python package, no separate deployment needed)
+- ✅ Agent sources configured (system repositories)
+- ✅ Skill sources empty by default (bundled skills only)
+- ✅ Progress bars showing sync and deployment phases for agents
 
 **💡 Optional Dependencies**:
 - `[monitor]` - Full monitoring dashboard with Socket.IO and async web server components