CLAUDE-MPM(1)

NAME

claude-mpmClaude Multi-Agent Project Manager — multi-channel orchestration, GitHub-first SDK mode, and plugin system for Claude

SYNOPSIS

$pip install claude-mpm

INFO

99 stars
20 forks
0 views
PythonAI & LLM

DESCRIPTION

Claude Multi-Agent Project Manager — multi-channel orchestration, GitHub-first SDK mode, and plugin system for Claude

README

Claude MPM - Multi-Agent Project Manager

PyPI version Python 3.11+ License: Elastic-2.0 Code style: ruff

A comprehensive workflow and agent management framework for Claude Code that transforms your AI coding assistant into a full-featured development platform with multi-agent orchestration, skills system, MCP integration, session management, and semantic code search.

⚠️ 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!

🧪 Beta available — v6.0.0b1: A new major version is ready for testing. It introduces a plugin install path, binary consolidation, and auto-migration. Stable users on v5.11.4 are unaffected — pre-releases do not auto-install.

Try the beta (plugin install — no pip needed):

claude plugin marketplace add bobmatnyc/claude-mpm-marketplace
claude plugin install claude-mpm@claude-mpm-marketplace

Try the beta (pip, explicit pin required):

pip install claude-mpm==6.0.0b1

Stay on stable (v5.11.4):

pip install claude-mpm        # installs latest stable automatically
uv tool install claude-mpm    # same — pre-releases are never selected

See Beta Guide for the full details.


Quick Start

Plugin Install (recommended for most users)

The fastest way to get started. No pip install required — provides hooks, 56 skills, slash commands, and MCP server config directly inside Claude Code.

# Add the MPM marketplace
claude plugin marketplace add bobmatnyc/claude-mpm-marketplace

Install the plugin

claude plugin install claude-mpm@claude-mpm-marketplace

This gives you: 6 hook events, 56 skills, 2 slash commands (/mpm-status, /mpm-help), and MCP server configuration — all without pip install.

Full Install (for power users)

For CLI commands, multi-agent orchestration, monitoring dashboard, and all integrations:

# Install the full package (from home directory)
cd ~
uv tool install "claude-mpm[monitor,data-processing]" --python 3.13

Then also install the plugin for Claude Code integration

claude plugin marketplace add bobmatnyc/claude-mpm-marketplace claude plugin install claude-mpm@claude-mpm-marketplace

See Installation below for all installation methods.


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 comprehensive AI development platform with:

🤖 Multi-Agent System

  • 47+ Specialized Agents - Python, TypeScript, Rust, Go, Java, Ruby, PHP, QA, Security, DevOps, and more
  • Intelligent PM Orchestration - Automatic task routing to specialist agents
  • Agent Sources - Deploy agents from Git repositories with ETag-based caching

🎯 Skills Framework

  • 56+ Bundled Skills - TDD, debugging, Docker, API design, security scanning, Git workflows
  • Progressive Disclosure - Skills load on-demand to optimize context usage
  • Three-Tier Organization - Bundled → User → Project priority resolution
  • Domain Authority System - Auto-generated agent/tool discovery skills for intelligent PM delegation
  • Skills Optimization - Intelligent project analysis with automated skill recommendations

🔌 MCP Integration (Model Context Protocol)

  • Google Workspace MCP - 34 tools for Gmail, Calendar, Drive, Docs, Tasks
  • Notion - 7 tools + bulk operations for databases, pages, markdown import
  • Confluence - 7 tools + bulk operations for pages, spaces, CQL search
  • Slack - User proxy for channels, messages, DMs, search
  • Semantic Code Search - AI-powered code discovery via mcp-vector-search
  • Ticket Management - GitHub, Linear, Jira integration via mcp-ticketer
  • Graph Memory - Persistent project knowledge via kuzu-memory

📊 Session & Workflow Management

  • Session Resume - Continue work with full context preservation
  • Auto-Pause - Automatic context summaries at 70%/85%/95% thresholds
  • Real-Time Dashboard - Live monitoring of agent activity
  • Hooks System - 15+ event hooks for custom workflows

🔐 Enterprise Features

  • OAuth 2.0 Integration - Secure Google Workspace authentication
  • Encrypted Token Storage - Fernet encryption with system keychain
  • 100+ CLI Commands - Comprehensive management interface
  • 60+ Services - Service-oriented architecture with event bus

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

Option A: Plugin Only (no pip required)

# Add the MPM marketplace and install the plugin
claude plugin marketplace add bobmatnyc/claude-mpm-marketplace
claude plugin install claude-mpm@claude-mpm-marketplace

This provides hooks, 56 skills, slash commands, and MCP config. For the full CLI, agents, monitor, and dashboard, continue with Option B.

Option B: Full Install (pip + plugin)

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/
  • 56+ 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

  • 56+ Bundled Skills covering Git, TDD, Docker, API design, security, debugging, and more
  • Three-Tier Organization: Bundled/user/project with priority resolution
  • Auto-Linking to relevant agents based on roles
  • Progressive Disclosure - Skills load on-demand to optimize context
  • 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
  • MCP Session Server (claude-mpm mcp serve session) for programmatic session management
  • 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 | → MCP Session Server

🔐 External Integrations

  • Browser-Based OAuth for secure authentication with MCP services
  • Google Workspace MCP built-in server with 34 tools for:
    • Gmail (5 tools): Search, read, send, draft, reply
    • Calendar (6 tools): List, get, create, update, delete events
    • Drive (7 tools): Search, read, create folders, upload, delete, move files
    • Docs (4 tools): Create, read, append, markdown-to-doc conversion
    • Tasks (12 tools): Full task and task list management
  • Notion MCP built-in server with 7 tools + bulk operations:
    • Query databases, get/create/update pages, search, markdown import
    • Setup: claude-mpm setup notion
  • Confluence MCP built-in server with 7 tools + bulk operations:
    • Get/create/update pages, search with CQL, list spaces, markdown import
    • Setup: claude-mpm setup confluence
  • Slack MCP user proxy with 12 tools:
    • Channels, messages, DMs, search - acts as authenticated user
    • Setup: claude-mpm setup slack
  • 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

Set up Notion (API token)

claude-mpm setup notion

Set up Confluence (URL + API token)

claude-mpm setup confluence

Set up Slack (OAuth user token)

claude-mpm setup slack

Check token status

claude-mpm oauth status workspace-mcp

List OAuth-capable services

claude-mpm oauth list

→ Google Workspace Setup | → Notion Setup | → Confluence Setup | → Slack Setup

⚡ Performance & Security

  • Near-Instant Startup — syncs agents and skills once per day; subsequent launches skip all network checks and start in ~100ms
  • Simplified Architecture with ~3,700 lines removed for better performance
  • Enhanced Security with comprehensive input validation
  • Intelligent Caching with hash-based invalidation and TTL-gated sync
  • 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

Force sync agents/skills from GitHub (overrides 24-hour TTL)

claude-mpm --force-sync

Skip sync for maximum startup speed

claude-mpm --no-sync

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

💡 Startup Performance: Claude MPM syncs agents and skills once per day. Subsequent launches are near-instant (~100ms). Use --force-sync to pull the latest content immediately or set CLAUDE_MPM_SYNC_TTL (seconds) to customize the sync interval.

💡 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


SDK Runtime Mode (Experimental)

New in v5.11.0 -- Claude MPM can now run the PM agent via the Claude Agent SDK instead of spawning a CLI subprocess. This enables programmatic control, real-time event streaming, and live session observability.

Backward Compatible: The default runtime is still CLI mode. Existing users do not need to change anything.

Enabling SDK Mode

# Via CLI flag
claude-mpm run --sdk

Via environment variable

export CLAUDE_MPM_RUNTIME=sdk claude-mpm run

Force CLI mode explicitly (useful to override auto-detection)

claude-mpm run --cli

Auto-detection: If the claude-agent-sdk Python package is installed and no flag or env var is set, SDK mode is selected automatically. Otherwise, CLI mode is used as the fallback.

New CLI Flags

FlagDescription
--sdkUse Agent SDK runtime (requires claude-agent-sdk)
--cliForce CLI subprocess runtime
--inject-port <PORT>Start message injection endpoint on PORT (default: 7856)

Environment variable: CLAUDE_MPM_RUNTIME=sdk or CLAUDE_MPM_RUNTIME=cli

Key Capabilities

Monitor Agent -- A background watchdog thread that monitors PM session health:

  • Context pressure warnings at configurable thresholds (70%, 80%, 90%, 95%)
  • Session duration and idle/stuck detection
  • Automatic warnings injected via the hook event bus

Message Injection -- External systems can send prompts to the running PM session:

# Start the injection endpoint
claude-mpm run --sdk --inject-port 7856

From another terminal or script

curl -X POST http://localhost:7856/inject
-H "Content-Type: application/json"
-d '{"prompt": "Check the status of PR #123"}'

The /mpm-message slash command also bridges messages to the PM session via the monitor agent's systemMessage channel.

Session Observability -- Live session state and activity feed via HTTP:

# Current session state (idle, processing, tool_call, etc.)
curl http://localhost:7856/session

Recent activity feed

curl http://localhost:7856/activity

Architecture Overview

The SDK runtime is built on an adapter pattern with clean separation of concerns:

  • AgentRuntime ABC -- Runtime-agnostic interface with run(), resume(), fork(), and run_with_hooks() methods
  • SDKAgentRunner -- In-process SDK implementation using claude-agent-sdk
  • CLIAgentRunner -- Subprocess adapter wrapping the existing ClaudeAdapter
  • create_runtime() factory -- Instantiates the correct backend based on config
  • RuntimeConfig -- Resolves runtime type from CLAUDE_MPM_RUNTIME env var or auto-detection
  • HookEventBus -- File-based message queue for sidecar agent to PM communication
  • SDKEventBridge -- Translates SDK events into MPM monitoring dashboard emissions
  • SessionStateTracker -- Thread-safe state machine for session observability
                  ┌─────────────────┐
                  │  create_runtime │
                  └────────┬────────┘
                           │
              ┌────────────┴────────────┐
              │                         │
     ┌────────▼────────┐      ┌────────▼────────┐
     │  SDKAgentRunner  │      │  CLIAgentRunner  │
     │  (in-process)    │      │  (subprocess)    │
     └────────┬────────┘      └─────────────────┘
              │
   ┌──────────┼──────────┐
   │          │          │
   ▼          ▼          ▼
Monitor    EventBridge  StateTracker
Agent      (SocketIO)   (/session)

Requirements

  • claude-agent-sdk Python package (optional -- only needed for SDK mode)
  • SDK mode is experimental and may change in future releases

What's New in v6.0

Beta status: v6.0.0b1 is currently in beta. See Beta Guide for install instructions and known limitations.

Validated in testing:

  • ✅ Binary consolidation
  • ✅ Auto-migration of .mcp.json configs
  • ✅ Plugin install and uninstall
  • ✅ Stop hook stale count fix
  • ✅ Agent workflow end-to-end

Plugin System (NEW)

Claude MPM can now be installed as a Claude Code plugin — no pip install required for core functionality:

claude plugin marketplace add bobmatnyc/claude-mpm-marketplace
claude plugin install claude-mpm@claude-mpm-marketplace

The plugin provides 6 hook events, 56 skills, 2 slash commands (/mpm-status, /mpm-help), and MCP server configuration. For the full CLI, agents, monitor, and dashboard, a pip install is still needed.

Binary Consolidation (BREAKING)

10 standalone binaries have been consolidated to 2:

BinaryPurpose
claude-mpmAll CLI commands + mcp serve <name> for MCP servers
claude-hookHook handler (performance-critical, stays separate)

Removed standalone binaries: claude-mpm-doctor, claude-mpm-monitor, claude-mpm-socketio, claude-mpm-ui, confluence-mcp, notion-mpm, mpm-session-server, mpm-session-server-http

The new claude-mpm mcp serve <name> subcommand replaces direct binary invocations. For example:

# Before (v5.x)
mpm-session-server --port 8080

After (v6.0)

claude-mpm mcp serve session --port 8080

Auto-Migration

Run claude-mpm migrate to automatically update old .mcp.json configurations to the new binary names. Migration also runs automatically on startup.

56 Bundled Skills

The skills library has grown from 44 to 56 bundled skills, covering additional development patterns and workflows.


Migration from v5.x

If you are upgrading from v5.x, follow these steps:

  1. Update the package:

    uv tool install "claude-mpm[monitor,data-processing]" --python 3.13 --force
    
  2. Run the migration command to update .mcp.json and other configs:

    claude-mpm migrate
    

    This rewrites references to removed binaries (e.g., mpm-session-server becomes claude-mpm mcp serve session). The migration also runs automatically on startup.

  3. Install the plugin (optional but recommended):

    claude plugin marketplace add bobmatnyc/claude-mpm-marketplace
    claude plugin install claude-mpm@claude-mpm-marketplace
    
  4. Backward compatibility: claude-mpm-doctor still works but prints a deprecation warning. Use claude-mpm doctor instead. All other removed binaries require updating to claude-mpm mcp serve <name>.


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


Strategic Direction: Delegated Automation & Cloud Dev Environments

Claude MPM is moving beyond local orchestration toward being the control plane for delegated agentic automation — where the PM spawns and manages Claude Code instances running in cloud dev environments rather than only on the local machine.

The Vision

Today, claude-mpm runs everything on your local machine. The next evolution: the PM stays as a lightweight controller while heavy implementation work is delegated to cloud-hosted Claude Code agents with isolated workspaces, full repo access, test runners, and deployment tools.

Each agent gets its own ephemeral environment (a GitHub Codespace, a Gitpod workspace, a remote Docker container, a CI runner) — pre-configured, disposable, and purpose-built for the task.

Foundation: What's Already Built

The pieces are in place:

CapabilityHow It's Used
SDK mode (--sdk)Runs Claude programmatically without a local terminal — the bridge to headless/remote execution
Channel Hub (--channels)Multi-session message bus connecting the local PM to agent sessions
GitHub first-class contextAutomatic PR/branch/repo state injection — cloud agents understand the codebase on arrival
MCP server auto-detectionAgents discover available tools at session start, no manual configuration

Phase 5+: Cloud Dev Sled Integration

The next major phases build on the channel hub:

Phase 5 — Remote Channel Adapters: Telegram and Slack adapters connect the PM to agents running anywhere. A message sent to the PM via Slack routes to the correct cloud agent session and streams the response back.

Phase 6 — Cloud Sled Launch: The PM can provision an ephemeral cloud dev environment (Codespaces, Gitpod, Daytona, remote container), launch Claude Code in SDK mode inside it, and register the session with the local Channel Hub. The PM delegates a task; the cloud agent does the work; results flow back through the channel.

Phase 7 — Fleet Coordination: Multiple cloud agents working in parallel on independent tasks, coordinated by the local PM. The PM owns task routing, progress tracking, and result aggregation. Individual agents are disposable — the PM is the persistent state.

Design Principles

  • Local PM, remote workers: The controller stays lightweight and local. Execution scales out to cloud environments.
  • Channels as the backbone: The Channel Hub (already built) is the messaging layer that connects PM to remote agents — no new protocol needed.
  • GitHub-native by default: Cloud agents start with full repo context automatically. No setup required per task.
  • SDK mode is the execution primitive: All remote agent execution goes through --sdk. The programmatic API is stable and already supports headless operation.
  • Ephemeral environments, persistent coordination: Cloud workspaces are created and destroyed per task. The PM's session state and task history persist locally.

Near-Term Milestones (Phase 4)

Before cloud sled work begins, Phase 4 completes the channel hub foundation:

  1. Telegram and Slack adapters (channel hub variants)
  2. Hub-CLI IPC bridge (channels list, channels auth talk to running hub)
  3. GitHub context injection in plain --sdk mode (not just channels mode)
  4. Test coverage for the channels and GitHub service layers

See docs/research/multi-channel-github-phase4-analysis-2026-03-26.md for the detailed Phase 4 analysis.


Documentation

📚 Complete Documentation Hub - Start here for all documentation!

Quick Links by User Type

👥 For Users

💻 For Developers

🤖 For Agent Creators

🚀 For Operations


Integrations

Claude MPM supports multiple integrations for enhanced functionality. See Complete Integration Documentation for detailed setup guides.

Core Integrations

External Services

  • Google Workspace MCP - Gmail, Calendar, Drive, Docs, Tasks (67 tools)
  • Slack - Slack workspace integration via user proxy
  • Notion - Notion databases and pages (7 MCP tools + bulk CLI)
  • Confluence - Confluence pages and spaces (7 MCP tools + bulk CLI)

Quick Setup

# Setup any integration with one command
claude-mpm setup <integration>

Examples:

claude-mpm setup kuzu-memory claude-mpm setup mcp-vector-search claude-mpm setup gworkspace-mcp # Canonical name (preferred) claude-mpm setup google-workspace-mcp # Legacy alias (also works) claude-mpm setup slack claude-mpm setup notion claude-mpm setup confluence

Setup multiple at once

claude-mpm setup kuzu-memory mcp-vector-search gworkspace-mcp

Integration Features:

  • One-command setup for all services
  • Secure OAuth 2.0 authentication (Google Workspace, Slack)
  • Encrypted token storage in system keychain
  • Automatic token refresh
  • MCP protocol for standardized tool interfaces
  • Bulk CLI operations for high-performance batch processing

Contributing

Contributions are welcome! Please see:

Development Workflow:

# Complete development setup
make dev-complete

Or step by step:

make setup-dev # Install in development mode make setup-pre-commit # Set up automated code formatting


📜 License

License

Licensed under the Elastic License 2.0 - free for internal use and commercial products.

Main restriction: Cannot offer as a hosted SaaS service without a commercial license.

📖 Licensing FAQ | 💼 Commercial licensing: bob@matsuoka.com


Credits

SEE ALSO

clihub3/27/2026CLAUDE-MPM(1)