bobmatnyc/claude-mpm

Claude Code를 위한 포괄적인 워크플로우 및 에이전트 관리 프레임워크로, 멀티 에이전트 오케스트레이션 (multi-agent orchestration), 스킬 시스템 (skills system), MCP 통합 (MCP integration), 세션 관리 (session management), 그리고 시맨틱 코드 검색 (semantic code search)을 통해 귀하의 AI 코딩 어시스턴트를 풀 피처(full-featured) 개발 플랫폼으로 변환합니다.

: Claude MPM⚠️ 중요: Claude Desktop(앱)이 아닌 Claude Code CLI(v2.1.3+)가 필요합니다. 모든 MCP 통합은 Claude Code의 CLI 인터페이스에서만 작동합니다.

Claude Code가 없으신가요? 다음에서 설치하세요: https://docs.anthropic.com/en/docs/claude-code

빠른 시작: 5분 안에 실행하려면 시작 가이드(Getting Started Guide)를 참조하세요!

현재 안정 버전: v6.1.0— 플러그인 설치 경로, 바이너리 통합, 그리고 자동 마이그레이션(auto-migration)이 포함되어 있습니다. v6.0 릴리스 노트는 베타 가이드(Beta Guide)를 참조하세요.

가장 빠르게 시작하는 방법입니다. pip install이 필요하지 않습니다 — Claude Code 내부에 훅 (hooks), 56개의 스킬 (skills), 슬래시 명령어 (slash commands), 그리고 MCP 서버 설정 (MCP server config)을 직접 제공합니다.

# MPM 마켓플레이스 추가
claude plugin marketplace add bobmatnyc/claude-mpm-marketplace
# 플러그인 설치
...

이를 통해 다음을 얻을 수 있습니다: 6개의 훅 이벤트 (hook events), 56개의 스킬 (skills), 2개의 슬래시 명령어 (slash commands) (/mpm-status, /mpm-help), 그리고 MCP 서버 설정 (MCP server configuration) — 이 모든 것이 pip install 없이 가능합니다.

CLI 명령어, 멀티 에이전트 오케스트레이션 (multi-agent orchestration), 모니터링 대시보드 (monitoring dashboard), 그리고 모든 통합을 위해서는:

# 전체 패키지 설치 (홈 디렉토리에서)
cd ~
uv tool install "claude-mpm[monitor,data-processing]" --python 3.13
...

모든 설치 방법은 아래의 설치(Installation) 섹션을 참조하세요.

• 👥
  비기술 사용자 (창업자/PM) - 리서치 모드 (Research Mode)를 사용하여 코드베이스를 조사하고 이해합니다 - 코딩 경험이 필요하지 않습니다.
• 💻
  개발자 - 시맨틱 코드 검색 (semantic code search) 및 고급 기능이 포함된 멀티 에이전트 개발 워크플로우
• 🏢
  팀 - 협업 패턴, 세션 관리 (session management), 그리고 조정된 워크플로우

Claude MPM은 Claude Code를 다음과 같은 포괄적인 AI 개발 플랫폼으로 변환합니다:

47개 이상의 전문 에이전트 (Specialized Agents)

• Python, TypeScript, Rust, Go, Java, Ruby, PHP, QA, Security, DevOps 등
  지능형 PM 오케스트레이션 (Intelligent PM Orchestration)
• 전문 에이전트로의 자동 작업 라우팅 (Task routing)
  에이전트 소스 (Agent Sources)
• ETag 기반 캐싱을 통한 Git 리포지토리로부터의 에이전트 배포

56개 이상의 번들링된 기술 (Bundled Skills)

• TDD, 디버깅 (debugging), Docker, API 설계 (API design), 보안 스캐닝 (security scanning), Git 워크플로우 (Git workflows)
  점진적 공개 (Progressive Disclosure)
• 컨텍스트 (context) 사용 최적화를 위해 기술을 온디맨드 (on-demand)로 로드
  3단계 조직 구조 (Three-Tier Organization)
• 번들 (Bundled) → 사용자 (User) → 프로젝트 (Project) 우선순위 해결
  도메인 권한 시스템 (Domain Authority System)
• 지능형 PM 위임을 위한 에이전트/도구 발견 기술 자동 생성
  기술 최적화 (Skills Optimization)
• 자동화된 기술 추천을 통한 지능형 프로젝트 분석

Google Workspace MCP

• Gmail, Calendar, Drive, Docs, Tasks를 위한 34개 도구
  Notion
• 데이터베이스, 페이지, 마크다운 (markdown) 가져오기를 위한 7개 도구 + 일괄 작업 (bulk operations)
  Confluence
• 페이지, 스페이스 (spaces), CQL 검색을 위한 7개 도구 + 일괄 작업 (bulk operations)
  Slack
• 채널, 메시지, DM, 검색을 위한 사용자 프록시 (User proxy)
  시맨틱 코드 검색 (Semantic Code Search)
• trusty-search를 통한 AI 기반 코드 발견
  티켓 관리 (Ticket Management)
• mcp-ticketer를 통한 GitHub, Linear, Jira 통합
  지속성 메모리 (Persistent Memory)
• trusty-memory를 통한 프로젝트 지식 저장소

세션 재개 (Session Resume)

• 전체 컨텍스트를 보존하며 작업 계속하기
  자동 일시정지 (Auto-Pause)
• 70%/85%/95% 임계값에서 자동 컨텍스트 요약 생성
  실시간 대시보드 (Real-Time Dashboard)
• 에이전트 활동 실시간 모니터링
  훅 시스템 (Hooks System)
• 커스텀 워크플로우를 위한 15개 이상의 이벤트 훅 (event hooks)

OAuth 2.0 통합 (OAuth 2.0 Integration)

• 안전한 Google Workspace 인증
  암호화된 토큰 저장 (Encrypted Token Storage)
• 시스템 키체인 (system keychain)과 Fernet 암호화 사용
  100개 이상의 CLI 명령어 (CLI Commands)
• 포괄적인 관리 인터페이스
  60개 이상의 서비스 (Services)
• 이벤트 버스 (event bus)를 갖춘 서비스 지향 아키텍처 (service-oriented architecture)

Python 3.11-3.13 (Python 3.13 권장; 3.14는 아직 지원되지 않음)
Claude Code CLI v2.1.3+ (필수!)
GitHub Token (기술 소스를 위해 권장)

Python 버전 경고:

• macOS 기본 Python 3.9는 너무 오래되었습니다. --python 3.13을 사용하세요.

• Python 3.13 권장 및 전체 테스트 완료

• Python 3.14는 아직 지원되지 않음 - 설치 실패 예정

# Claude Code가 설치되었는지 확인
claude --version
# 설치되지 않은 경우, 다음에서 가져오세요:
...

# MPM 마켓플레이스를 추가하고 플러그인을 설치합니다
claude plugin marketplace add bobmatnyc/claude-mpm-marketplace
claude plugin install claude-mpm@claude-mpm-marketplace

이를 통해 훅 (hooks), 56개의 스킬 (skills), 슬래시 명령어 (slash commands) 및 MCP 설정을 제공합니다. 전체 CLI, 에이전트 (agents), 모니터 (monitor) 및 대시보드 (dashboard)를 사용하려면 옵션 B를 계속 진행하세요.

중요: 클론(cloned)된 git 리포지토리 내부가 아니라, 반드시 **홈 디렉토리 (home directory)**에서 설치하세요.

uv (권장):

# 홈 디렉토리에서 (중요!)
cd ~
# Python 3.13으로 설치 (3.9 또는 3.14 아님)
...

Homebrew (macOS):

brew tap bobmatnyc/tools
brew install claude-mpm

pipx:

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

이 단계들은 claude-mpm doctor를 실행하기 전에 완료되어야 합니다.

# 필요한 디렉토리 생성
mkdir -p ~/.claude/{responses,memory,logs}
# 에이전트 배포
...

# 진단 실행 (위의 설정을 완료한 후)
claude-mpm doctor --verbose
# 버전 확인
...

확인 가능한 사항:

• ~/.claude/agents/에 47개 이상의 에이전트 배포됨
• 56개 이상의 번들 스킬 (Python 패키지에 포함)
• 에이전트 소스 구성 완료
• 모든 doctor 체크 통과

권장 파트너: 향상된 기능을 위해 다음 보조 도구들을 설치하세요:

uv tool install trusty-memory --python 3.13
uv tool install trusty-search --python 3.13
uv tool install mcp-ticketer --python 3.13
...

도구 버전 관리: 프로젝트 간의 Python/uv 버전 충돌을 피하기 위해 ASDF 버전 관리자를 사용하세요.

47개 이상의 특화된 에이전트 (Specialized Agents): 모든 개발 요구 사항을 충족하는 Git 리포지토리로부터 제공
스마트 작업 라우팅 (Smart Task Routing): PM 에이전트가 전문가에게 지능적으로 위임
세션 관리 (Session Management): 원활한 연속성을 위한 --resume 플래그 사용
재개 로그 시스템 (Resume Log System): 70%/85%/95% 임계값에서 자동 10k-토큰 요약 제공

큐레이션된 콘텐츠 (Curated Content)

• 리포지토리로부터 자동으로 배포되는 47개 이상의 에이전트
  항상 최신 상태 유지 (Always Up-to-Date)
• ETag 기반 캐싱을 통한 대역폭 95% 이상 절감
  계층적 BASE-AGENT.md
• 템플릿 상속 및 DRY (Don't Repeat Yourself) 원칙 적용
  커스텀 리포지토리 (Custom Repositories)
• claude-mpm agent-source add 명령어를 통해 추가 가능

56개 이상의 번들링된 기술 (Bundled Skills)

• Git, TDD, Docker, API 설계, 보안, 디버깅 등을 포함
  3단계 조직화 (Three-Tier Organization): 번들/사용자/프로젝트 단위 구성 및 우선순위 기반 해결
  자동 연결 (Auto-Linking): 역할에 기반하여 관련 에이전트와 자동 연결
  점진적 공개 (Progressive Disclosure): 컨텍스트 최적화를 위해 기술을 필요할 때만 로드
  커스텀 기술 (Custom Skills): .claude/skills/ 디렉토리 또는 기술 리포지토리를 통해 추가 가능

AI 기반 탐색 (AI-Powered Discovery)

• trusty-search 통합을 통한 탐색
  의도 기반 검색 (Find by Intent): 단순 키워드가 아닌 의도로 검색 (예: "authentication logic" 검색 시 관련 코드 탐색)
  패턴 인식 (Pattern Recognition): 유사한 구현 사례를 발견하기 위한 기능
  실시간 업데이트 (Live Updates): 코드 변경 사항을 자동으로 추적

멀티 프로젝트 오케스트레이션 (Multi-Project Orchestration)

• 코드베이스 전반에 걸친 자율적인 AI 조정 기능
  Tmux 통합 (Tmux Integration): 격리된 프로젝트 환경 및 세션 관리를 위한 지원
  이벤트 기반 아키텍처 (Event-Driven Architecture): 프로젝트 간 통신을 위한 인박스 (inbox) 시스템 제공
  LLM 기반 의사결정 (LLM-Powered Decisions): OpenRouter를 통한 자율적인 작업 큐 (work queue) 처리
  실시간 모니터링 (Real-Time Monitoring): 상태 추적 (IDLE, WORKING, BLOCKED, PAUSED, ERROR) 지원

⚠️ 실험적 기능 (Experimental)

• API 및 CLI 인터페이스는 변경될 수 있음

MCP 통합 (MCP Integration)

• Model Context Protocol (MCP) 완전 지원
  MCP 세션 서버 (MCP Session Server): claude-mpm mcp serve session 명령어를 통한 프로그래밍 방식의 세션 관리
  실시간 모니터링 (Real-Time Monitoring): --monitor 플래그 및 웹 대시보드를 통해 제공
  멀티 프로젝트 지원 (Multi-Project Support): 세션별 작업 디렉토리 지원
  Git 통합 (Git Integration): diff 보기 및 변경 사항 추적 지원

→ 더 알아보기: MCP Gateway | → MCP Session Server

**브라우저 기반 OAuth (Browser-Based OAuth)**를 통한 MCP 서비스와의 안전한 인증

Google Workspace MCP
**34개의 도구 (tools)**를 포함한 내장 서버:

• Gmail (5개 도구): 검색 (Search), 읽기 (read), 보내기 (send), 초안 작성 (draft), 답장 (reply)
• Calendar (6개 도구): 이벤트 목록 (List), 가져오기 (get), 생성 (create), 업데이트 (update), 삭제 (delete)
• Drive (7개 도구): 검색 (Search), 읽기 (read), 폴더 생성 (create folders), 업로드 (upload), 파일 삭제 (delete), 파일 이동 (move files)
• Docs (4개 도구): 생성 (Create), 읽기 (read), 내용 추가 (append), 마크다운-문서 변환 (markdown-to-doc conversion)
• Tasks (12개 도구): 전체 작업 및 작업 목록 관리

Notion MCP
7개의 도구 (tools) 및 일괄 작업 (bulk operations)을 포함한 내장 서버:

• 데이터베이스 쿼리 (Query databases), 페이지 가져오기/생성/업데이트 (get/create/update pages), 검색 (search), 마크다운 가져오기 (markdown import)
• 설정 (Setup):
  claude-mpm setup notion

Confluence MCP
7개의 도구 (tools) 및 일괄 작업 (bulk operations)을 포함한 내장 서버:

• 페이지 가져오기/생성/업데이트 (Get/create/update pages), CQL을 이용한 검색 (search with CQL), 공간 목록 (list spaces), 마크다운 가져오기 (markdown import)
• 설정 (Setup):
  claude-mpm setup confluence

Slack MCP
**12개의 도구 (tools)**를 갖춘 사용자 프록시 (user proxy):

• 채널 (Channels), 메시지 (messages), DM, 검색 (search) - 인증된 사용자로 동작
• 설정 (Setup):
  claude-mpm setup slack-mpm

암호화된 토큰 저장 (Encrypted Token Storage)
시스템 키체인 (system keychain)과 Fernet 암호화를 사용

자동 토큰 갱신 (Automatic Token Refresh)
만료를 원활하게 처리

# Google Workspace OAuth 설정
claude-mpm oauth setup workspace-mcp
# Notion 설정 (API 토큰)
...

→ Google Workspace 설정 | → Notion 설정 | → Confluence 설정 | → Slack 설정

ZTK 셸 출력 압축 (ZTK Shell Output Compression)
— 자동 번들 바이너리를 통해 셸 명령(find, grep, ls, git 등)의 토큰 사용량을 80–97% 감소시킴

거의 즉각적인 시작 (Near-Instant Startup)
— 에이전트와 스킬을 하루에 한 번 동기화하며, 이후 실행 시에는 모든 네트워크 확인을 건너뛰고 약 100ms 내에 시작

단순화된 아키텍처 (Simplified Architecture)
— 더 나은 성능을 위해 약 3,700줄의 코드 제거

강화된 보안 (Enhanced Security)
— 포괄적인 입력 검증 (input validation) 적용

지능형 캐싱 (Intelligent Caching)
— 해시 기반 무효화 (hash-based invalidation) 및 TTL 제한 동기화 적용

메모리 관리 (Memory Management)
— 대규모 대화 기록을 위한 정리 명령 (cleanup commands) 제공

→ 더 알아보기: 아키텍처 (Architecture) | → ZTK 압축 가이드 (ZTK Compression Guide)

심리스한 업데이트 (Seamless Updates): 업데이트 후 첫 실행 시 자동 구성 마이그레이션 (automatic configuration migration) 제공
일회성 수정 (One-Time Fixes): 캐시 구조 재편성 (cache restructuring) 및 구성 변경 사항 처리
비차단 (Non-Blocking): 실패 시 경고를 로그에 기록하지만 시작을 중단하지 않음
추적 가능 (Tracked): ~/.claude-mpm/migrations.yaml에 기록됨

# 대화형 모드 시작
claude-mpm
# 모니터링 대시보드와 함께 시작
...

💡 시작 성능 (Startup Performance): Claude MPM은 에이전트 (agents)와 스킬 (skills)을 하루에 한 번 동기화합니다. 이후 실행은 거의 즉각적입니다 (~100ms). 최신 콘텐츠를 즉시 가져오려면 --force-sync를 사용하거나, CLAUDE_MPM_SYNC_TTL (초 단위)을 설정하여 동기화 간격을 사용자 정의할 수 있습니다.

💡 업데이트 확인 (Update Checking): Claude MPM은 시작 시 자동으로 업데이트를 확인하고 Claude Code와의 호환성을 검증합니다. ~/.claude-mpm/configuration.yaml에서 설정하거나 docs/update-checking.md를 참조하세요.

Claude MPM을 사용하면 ~/.claude-mpm/config/configuration.yaml을 통해 Planner를 포함한 모든 에이전트를 특정 모델 티어 (model tier) 또는 전체 모델 이름으로 고정(pin)할 수 있습니다.

별칭 (Alias)	연결되는 모델 (Resolves to)
haiku	claude-3-5-haiku-20241022
sonnet	claude-sonnet-4-5
opus	claude-opus-4-7

별칭 대신 Anthropic의 전체 모델 이름 (예: claude-opus-4-7)도 사용할 수 있습니다.

• configuration.yaml 내 models.agents.<agent-name>의 Agent 도구 호출 시 명시적인 model= 인자
• 에이전트의 프론트매터 (frontmatter, .claude/agents/*.md) 내 model: 필드
• 내장된 리소스 티어 (resource-tier) 기본값

# ~/.claude-mpm/config/configuration.yaml
models:
# Planner 에이전트의 모델을 재정의 (Override)
...

models.planning은 특히 Planner 에이전트를 위한 단축키입니다. models.agents.<name>은 agent_id (또는 .md가 없는 파일 이름)가 <name>과 일치하는 모든 에이전트에 적용됩니다.

프로젝트 수준의 재정의 (overrides)는 저장소 루트 내부의 .claude-mpm/configuration.yaml에 배치할 수 있으며, 해당 프로젝트에 대해 전역 파일보다 우선순위를 가집니다.

v5.11.0 신규 기능 -- Claude MPM은 이제 CLI 서브프로세스 (subprocess)를 생성하는 대신 Claude Agent SDK를 통해 PM 에이전트 (agent)를 실행할 수 있습니다. 이를 통해 프로그래밍 방식의 제어 (programmatic control), 실시간 이벤트 스트리밍 (real-time event streaming), 그리고 라이브 세션 관측성 (live session observability)이 가능해집니다.

하위 호환성 (Backward Compatible): 기본 런타임 (runtime)은 여전히 CLI 모드입니다. 기존 사용자들은 아무것도 변경할 필요가 없습니다.

# CLI 플래그 (flag)를 통해 실행
claude-mpm run --sdk
# 환경 변수 (environment variable)를 통해 실행
...

자동 감지 (Auto-detection): 만약 claude-agent-sdk Python 패키지가 설치되어 있고 플래그나 환경 변수가 설정되지 않았다면, SDK 모드가 자동으로 선택됩니다. 그렇지 않으면 CLI 모드가 폴백 (fallback)으로 사용됩니다.

플래그 (Flag)	설명
--sdk	Agent SDK 런타임 사용 (claude-agent-sdk 필요)
--cli	CLI 서브프로세스 런타임 강제 사용
--inject-port <PORT>	PORT에서 메시지 주입 (message injection) 엔드포인트 시작 (기본값: 7856)

환경 변수 (Environment variable): CLAUDE_MPM_RUNTIME=sdk 또는 CLAUDE_MPM_RUNTIME=cli

에이전트 모니터링 (Monitor Agent) -- PM 세션의 상태 (health)를 모니터링하는 백그라운드 와치독 (watchdog) 스레드:

• 설정 가능한 임계값 (70%, 80%, 90%, 95%)에서의 컨텍스트 압박 (Context pressure) 경고
• 세션 지속 시간 및 유휴/멈춤 (idle/stuck) 감지
• 훅 이벤트 버스 (hook event bus)를 통해 주입되는 자동 경고

메시지 주입 (Message Injection) -- 외부 시스템에서 실행 중인 PM 세션으로 프롬프트 (prompts)를 보낼 수 있습니다:

# 주입 엔드포인트 시작
claude-mpm run --sdk --inject-port 7856
# 다른 터미널 또는 스크립트에서 실행
...

/mpm-message