claude-mpm
Advanced tools
NPM wrapper for claude-mpm Python package - Requires Python 3.8+. Orchestrate Claude with agent delegation and ticket tracking
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.
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.
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.
Claude MPM transforms Claude Code into a comprehensive AI development platform with:
Python Version Warning:
- macOS default Python 3.9 is too old - use
--python 3.13flag- 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
# 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.
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]"
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
# 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:
~/.claude/agents/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.
--resume flag for seamless continuity→ Learn more: Multi-Agent Development
claude-mpm agent-source add.claude/skills/ or skill repositories→ Learn more: Developer Use Cases
claude-mpm mcp serve session) for programmatic session management--monitor flag and web dashboard→ Learn more: MCP Gateway | → MCP Session Server
claude-mpm setup notionclaude-mpm setup confluenceclaude-mpm setup slack-mpm# 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
~/.claude-mpm/migrations.yaml→ Learn more: Startup Migrations
# 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
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.
# 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.
| 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
Monitor Agent -- A background watchdog thread that monitors PM session health:
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
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() methodsSDKAgentRunner -- In-process SDK implementation using claude-agent-sdkCLIAgentRunner -- Subprocess adapter wrapping the existing ClaudeAdaptercreate_runtime() factory -- Instantiates the correct backend based on configRuntimeConfig -- Resolves runtime type from CLAUDE_MPM_RUNTIME env var or auto-detectionHookEventBus -- File-based message queue for sidecar agent to PM communicationSDKEventBridge -- Translates SDK events into MPM monitoring dashboard emissionsSessionStateTracker -- Thread-safe state machine for session observability ┌─────────────────┐
│ create_runtime │
└────────┬────────┘
│
┌────────────┴────────────┐
│ │
┌────────▼────────┐ ┌────────▼────────┐
│ SDKAgentRunner │ │ CLIAgentRunner │
│ (in-process) │ │ (subprocess) │
└────────┬────────┘ └─────────────────┘
│
┌──────────┼──────────┐
│ │ │
▼ ▼ ▼
Monitor EventBridge StateTracker
Agent (SocketIO) (/session)
claude-agent-sdk Python package (optional -- only needed for SDK mode)Released in v6.0:
.mcp.json configsClaude 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.
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
Run claude-mpm migrate to automatically update old .mcp.json configurations to the new binary names. Migration also runs automatically on startup.
The skills library has grown from 44 to 56 bundled skills, covering additional development patterns and workflows.
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>.
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
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.
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.
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 |
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.
--sdk. The programmatic API is stable and already supports headless operation.Before cloud sled work begins, Phase 4 completes the channel hub foundation:
channels list, channels auth talk to running hub)--sdk mode (not just channels mode)See docs/research/multi-channel-github-phase4-analysis-2026-03-26.md for the detailed Phase 4 analysis.
📚 Complete Documentation Hub - Start here for all documentation!
doctor command with auto-fixClaude MPM supports multiple integrations for enhanced functionality. See Complete Integration Documentation for detailed setup guides.
# 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:
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
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
FAQs
NPM wrapper for claude-mpm Python package - Requires Python 3.8+. Orchestrate Claude with agent delegation and ticket tracking
We found that claude-mpm demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Company News
Socket won two 2026 Reppy Awards from RepVue, ranking in the top 5% of all sales orgs. AE Alexandra Lister shares what it's like to grow a sales career here.
Security News
NIST will stop enriching most CVEs under a new risk-based model, narrowing the NVD's scope as vulnerability submissions continue to surge.
Company News
/Security News
Socket is an initial recipient of OpenAI's Cybersecurity Grant Program, which commits $10M in API credits to defenders securing open source software.