claude-mpm

v6.2.0

Published

13 hours ago

NPM wrapper for claude-mpm Python package - Requires Python 3.8+. Orchestrate Claude with agent delegation and ticket tracking

Downloads

5,667

0High
0Medium
0Low

bobmatnyc

claude ai orchestration multi-agent project-management cli claude-code anthropic

Claude MPM - Multi-Agent Project Manager

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!

Current stable version: v6.1.0 — plugin install path, binary consolidation, and auto-migration. See Beta Guide for v6.0 release notes.

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

Python 3.11-3.13 (Python 3.13 recommended; 3.14 NOT yet supported)
Claude Code CLI v2.1.3+ (required!)
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-mpm
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-mpm

# 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

| Flag | Description | |------|-------------| | --sdk | Use Agent SDK runtime (requires claude-agent-sdk) | | --cli | Force 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

Released in v6.0:

✅ 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:

| Binary | Purpose | |--------|---------| | claude-mpm | All CLI commands + mcp serve <name> for MCP servers | | claude-hook | Hook 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:

Update the package:

uv tool install "claude-mpm[monitor,data-processing]" --python 3.13 --force

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.

Install the plugin (optional but recommended):

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

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:

| Capability | How 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 context | Automatic PR/branch/repo state injection — cloud agents understand the codebase on arrival | | MCP server auto-detection | Agents 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:

Telegram and Slack adapters (channel hub variants)
Hub-CLI IPC bridge (channels list, channels auth talk to running hub)
GitHub context injection in plain --sdk mode (not just channels mode)
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

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

💻 For Developers

🏗️ Architecture Overview - Service-oriented system design
💻 Developer Guide - Complete development documentation
🧪 Contributing - How to contribute
📊 API Reference - Complete API documentation

🤖 For Agent Creators

🤖 Agent System - Complete agent development guide
📝 Creation Guide - Step-by-step tutorials
📋 Schema Reference - Agent format specifications

🚀 For Operations

🚀 Deployment - Release management & versioning
📊 Monitoring - Real-time dashboard & metrics
🐛 Troubleshooting - Enhanced doctor command with auto-fix

Integrations

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

Core Integrations

kuzu-memory - Graph-based semantic memory for project context
mcp-vector-search - AI-powered semantic code search and discovery

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-mpm
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:

Contributing Guide - How to contribute
Code Formatting - Code quality standards
Project Structure - Codebase organization

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

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: [email protected]

Credits

Based on claude-multiagent-pm
Enhanced for Claude Code (CLI) integration
Built with ❤️ by the Claude MPM community