Claude MPM - Multi-Agent Project Manager

A powerful orchestration framework for Claude Code (CLI) that enables multi-agent workflows, session management, and real-time monitoring through a streamlined Rich-based interface.

⚠️ Important: Claude MPM requires Claude Code CLI (v2.1.3+), not Claude Desktop (app). All MCP integrations work with Claude Code's CLI interface only.

Don't have Claude Code? Install from: https://docs.anthropic.com/en/docs/claude-code

Quick Start: See Getting Started Guide to get running in 5 minutes!

---

Who Should Use Claude MPM?

• 👥 Non-Technical Users (Founders/PMs) - Research and understand codebases using Research Mode - no coding experience required
• 💻 Developers - Multi-agent development workflows with semantic code search and advanced features
• 🏢 Teams - Collaboration patterns, session management, and coordinated workflows

---

What is Claude MPM?

Claude MPM transforms Claude Code into a multi-agent orchestration platform with:

• 47+ Specialized Agents - From Git repositories (Python, Rust, QA, Security, Ops, etc.)
• Intelligent Task Routing - PM agent delegates work to specialist agents
• Session Management - Resume previous sessions with full context preservation
• Semantic Code Search - AI-powered discovery of existing code and patterns
• Real-Time Monitoring - Live dashboard showing agent activity and performance
• Git Repository Integration - Always up-to-date agents and skills from curated repositories

---

Quick Installation

Prerequisites

1. Python 3.11-3.13 (Python 3.13 recommended; 3.14 NOT yet supported)
2. Claude Code CLI v2.1.3+ (required!)
3. GitHub Token (recommended for skill sources)

Python Version Warning:

• macOS default Python 3.9 is too old - use --python 3.13 flag
• Python 3.13 is recommended and fully tested
• Python 3.14 is NOT yet supported - installation will fail

# Verify Claude Code is installed
claude --version

# If not installed, get it from:
# https://docs.anthropic.com/en/docs/claude-code

# Set GitHub token (recommended - avoids rate limits)
export GITHUB_TOKEN=your_github_token

Install Claude MPM

IMPORTANT: Install from your home directory, NOT from within a cloned git repository.

uv (recommended):

# From home directory (IMPORTANT!)
cd ~

# Install with Python 3.13 (not 3.9 or 3.14)
uv tool install claude-mpm[monitor,data-processing] --python 3.13

Homebrew (macOS):

brew tap bobmatnyc/tools
brew install claude-mpm

pipx:

cd ~
pipx install "claude-mpm[monitor]"

Post-Installation Setup (Required)

These steps must be completed before running claude-mpm doctor:

# Create required directories
mkdir -p ~/.claude/{responses,memory,logs}

# Deploy agents
claude-mpm agents deploy

# Add skill source (recommended)
claude-mpm skill-source add https://github.com/bobmatnyc/claude-mpm-skills

Verify Installation

# Run diagnostics (after completing setup above)
claude-mpm doctor --verbose

# Check versions
claude-mpm --version
claude --version

# Auto-configure your project
cd ~/your-project
claude-mpm auto-configure

What You Should See:

• 47+ agents deployed to ~/.claude/agents/
• 17 bundled skills (in Python package)
• Agent sources configured
• All doctor checks passing

Recommended Partners: Install these companion tools for enhanced capabilities:

uv tool install kuzu-memory --python 3.13
uv tool install mcp-vector-search --python 3.13
uv tool install mcp-ticketer --python 3.13
uv tool install mcp-browser --python 3.13

Tool Version Management: Use ASDF version manager to avoid Python/uv version conflicts across projects.

---

Key Features

🎯 Multi-Agent Orchestration

• 47+ Specialized Agents from Git repositories covering all development needs
• Smart Task Routing via PM agent intelligently delegating to specialists
• Session Management with --resume flag for seamless continuity
• Resume Log System with automatic 10k-token summaries at 70%/85%/95% thresholds

→ Learn more: Multi-Agent Development

📦 Git Repository Integration

• Curated Content with 47+ agents automatically deployed from repositories
• Always Up-to-Date with ETag-based caching (95%+ bandwidth reduction)
• Hierarchical BASE-AGENT.md for template inheritance and DRY principles
• Custom Repositories via claude-mpm agent-source add

→ Learn more: Agent Sources

🎯 Skills System

• 17 Bundled Skills covering Git, TDD, Docker, API docs, testing, and more
• Three-Tier Organization: Bundled/user/project with priority resolution
• Auto-Linking to relevant agents based on roles
• Custom Skills via .claude/skills/ or skill repositories

→ Learn more: Skills Guide

🔍 Semantic Code Search

• AI-Powered Discovery with mcp-vector-search integration
• Find by Intent not just keywords ("authentication logic" finds relevant code)
• Pattern Recognition for discovering similar implementations
• Live Updates tracking code changes automatically

→ Learn more: Developer Use Cases

🧪 MPM Commander (ALPHA)

• Multi-Project Orchestration with autonomous AI coordination across codebases
• Tmux Integration for isolated project environments and session management
• Event-Driven Architecture with inbox system for cross-project communication
• LLM-Powered Decisions via OpenRouter for autonomous work queue processing
• Real-Time Monitoring with state tracking (IDLE, WORKING, BLOCKED, PAUSED, ERROR)
• ⚠️ Experimental - API and CLI interface subject to change

→ Commander Documentation

🔌 Advanced Integration

• MCP Integration with full Model Context Protocol support
• Real-Time Monitoring via --monitor flag and web dashboard
• Multi-Project Support with per-session working directories
• Git Integration with diff viewing and change tracking

→ Learn more: MCP Gateway

🔐 OAuth & Google Workspace Integration

• Browser-Based OAuth for secure authentication with MCP services
• Google Workspace MCP built-in server for Gmail, Calendar, and Drive
• Encrypted Token Storage using Fernet encryption with system keychain
• Automatic Token Refresh handles expiration seamlessly

# Set up Google Workspace OAuth
claude-mpm oauth setup workspace-mcp

# Check token status
claude-mpm oauth status workspace-mcp

# List OAuth-capable services
claude-mpm oauth list

→ Learn more: OAuth Setup Guide

⚡ Performance & Security

• Simplified Architecture with ~3,700 lines removed for better performance
• Enhanced Security with comprehensive input validation
• Intelligent Caching with ~200ms faster startup via hash-based invalidation
• Memory Management with cleanup commands for large conversation histories

→ Learn more: Architecture

⚙️ Automatic Migrations

• Seamless Updates with automatic configuration migration on first startup after update
• One-Time Fixes for cache restructuring and configuration changes
• Non-Blocking failures log warnings but do not stop startup
• Tracked in ~/.claude-mpm/migrations.yaml

→ Learn more: Startup Migrations

---

Quick Usage

# Start interactive mode
claude-mpm

# Start with monitoring dashboard
claude-mpm run --monitor

# Resume previous session
claude-mpm run --resume

# Semantic code search
claude-mpm search "authentication logic"
# or inside Claude Code:
/mpm-search "authentication logic"

# Health diagnostics
claude-mpm doctor

# Verify MCP services
claude-mpm verify

# Manage memory
claude-mpm cleanup-memory

💡 Update Checking: Claude MPM automatically checks for updates and verifies Claude Code compatibility on startup. Configure in ~/.claude-mpm/configuration.yaml or see docs/update-checking.md.

→ Complete usage examples: User Guide

---

What's New in v5.0

Git Repository Integration for Agents & Skills

• 📦 Massive Library: 47+ agents and hundreds of skills deployed automatically
• 🏢 Official Content: Anthropic's official skills repository included by default
• 🔧 Fully Extensible: Add your own repositories with immediate testing
• 🌳 Smart Organization: Hierarchical BASE-AGENT.md inheritance
• 📊 Clear Visibility: Two-phase progress bars (sync + deployment)
• ✅ Fail-Fast Testing: Test repositories before they cause startup issues

Quick Start with Custom Repositories:

# Add custom agent repository
claude-mpm agent-source add https://github.com/yourorg/your-agents

# Add custom skill repository
claude-mpm skill-source add https://github.com/yourorg/your-skills

# Test repository without saving
claude-mpm agent-source add https://github.com/yourorg/your-agents --test

→ Full details: What's New

---

Documentation

📚 Complete Documentation Hub - Start here for all documentation!

Quick Links by User Type

👥 For Users

• 🚀 5-Minute Quick Start - Get running immediately
• 📦 Installation Guide - All installation methods
• 📖 User Guide - Complete user documentation
• ❓ FAQ - Common questions answered

💻 For Devel