claude-peers로 구성하는 Claude Code 멀티에이전트 협업

독립된 Claude Code 세션을 연결하는 MCP 서버

Claude Code 세션을 여러 개 실행해도 각 세션은 서로의 존재나 작업 상태를 알지 못한다. 프론트엔드 세션이 API 변경을 끝냈더라도 백엔드 세션에 직접 알릴 통로가 없고, 작업 완료 신호 역시 별도로 전달해야 한다.

Louis Lva(louislva)가 공개한 claude-peers-mcp는 이 단절을 해소하는 오픈소스 MCP(Model Context Protocol) 서버다. GitHub의 louislva/claude-peers-mcp 저장소에서 소스코드와 설치 방법을 확인할 수 있다. 같은 머신에서 실행 중인 Claude Code 세션을 찾아내고, 세션 사이에 즉석 메시지를 교환하도록 만든 도구다.

프론트엔드 레포지토리를 맡은 세션 A가 백엔드 레포지토리의 세션 B에 API 스펙 변경을 알리거나, B가 작업 완료를 A에 회신하는 식으로 사용할 수 있다. 여러 AI 에이전트가 마이크로서비스를 나눠 병렬 작업하는 상황과 잘 맞는다.

통신 범위는 동일 머신의 localhost로 제한된다. 원격 머신 사이의 통신은 지원하지 않으며, 용도도 로컬 멀티에이전트 워크플로우에 맞춰져 있다.

중앙 브로커가 세션 사이의 메시지를 중계한다

전체 구조는 중앙 허브와 여러 스포크로 나뉜다. 브로커 데몬이 허브를 맡고, 각 Claude Code 세션에 붙은 MCP 서버가 스포크로 동작한다.

broker.ts로 구현된 브로커 데몬은 localhost:7899에서 HTTP 서버로 실행된다. SQLite 데이터베이스에 등록된 Claude Code 피어 정보를 저장하고, 피어 사이의 메시지를 목적지로 전달한다. 첫 번째 Claude Code 세션이 시작될 때 자동으로 기동되고 마지막 세션이 종료되면 정리된다. 응답하지 않는 죽은 피어도 목록에서 자동 제거된다.

각 세션에는 server.ts MCP 서버 인스턴스가 하나씩 스폰된다. 이 서버는 브로커에 현재 작업 디렉토리와 git 루트 정보를 포함해 자신을 등록한다. 이후 매 1초마다 브로커를 폴링해 도착한 메시지를 확인하고, 수신 내용을 claude/channel 프로토콜로 Claude 세션에 즉시 푸시한다.

OPENAI_API_KEY 환경 변수가 설정된 경우에는 세션 시작 시 gpt-5.4-nano 모델이 현재 작업에 관한 짧은 요약을 생성한다. 다른 피어는 이 요약을 보고 해당 세션의 역할과 협업 필요성을 판단할 수 있다. 비용은 수 센트 수준이다.

⤢✕

역할과 의존성에 따라 협업 구조를 고른다

여러 세션을 연결하는 것만으로 협업 방식이 결정되지는 않는다. 작업을 누가 나누고, 어떤 순서로 전달하며, 결과를 어디에서 합칠지 먼저 정해야 한다.

오케스트레이터-워커 구조에서는 한 세션이 전체 작업을 분해해 다른 세션에 서브태스크를 할당한다. 워커들은 독립적으로 실행한 결과를 오케스트레이터에게 돌려준다. 대규모 코드베이스 리팩토링이나 여러 레포지토리를 함께 이전하는 작업에 적용할 수 있다.

계층을 두지 않는 피어 협업도 가능하다. 각 세션이 대등한 위치에서 공유 태스크 목록의 작업을 가져가고 처리 상태를 갱신하는 플랫 구조다. Anthropic의 Claude Code Agent Teams도 에이전트들이 공유 태스크 리스트를 실시간으로 업데이트하는 이 패턴을 채택했다.

앞 단계의 결과가 다음 단계의 입력이 되어야 한다면 파이프라인이 맞는다. 코드 생성에서 리뷰, 테스트, 배포로 이어지는 CI/CD 흐름을 각 AI 에이전트에 맡기는 방식이다. 서로 의존하지 않는 작업은 병렬로 처리하고, 의존성이 높은 부분은 순차 파이프라인으로 연결하는 혼합 구성이 실용적이다.

컨텍스트는 분리하고 필요한 정보만 전달한다

claude-peers는 연결된 세션의 컨텍스트를 하나로 합치지 않는다. 각 세션은 독립적인 컨텍스트 창을 유지하고, 브로커에 명시적으로 보낸 메시지만 다른 세션과 공유한다.

이 격리는 한 세션의 전체 작업 문맥이 다른 세션에 섞이는 일을 막는다. 에이전트마다 담당 영역에 집중할 수 있는 대신, API 스펙 변경이나 공통 인터페이스 정의처럼 함께 알아야 할 정보는 별도의 메시지로 작성해야 한다. 따라서 협업 품질은 메시지에 어떤 배경과 결과를 담는지에 크게 좌우된다.

병렬 코딩 세션을 운영하는 흐름

각 Claude Code 세션은 서로 다른 레포지토리나 기능 도메인의 디렉토리에서 시작한다. 기동된 세션은 브로커에 자동 등록되고 피어 목록에 나타난다.

조율을 맡은 세션은 list_peers 도구로 활성 피어를 조회한다. 디렉토리, git 브랜치, 최근 파일과 피어 요약을 확인한 뒤 작업을 맡길 세션을 고른다. 태스크는 send_message 도구로 특정 피어 ID에 전달하며, 수신 세션은 메시지를 받은 뒤 작업을 시작한다.

완료된 결과는 워커가 다시 오케스트레이터에게 메시지로 보낸다. 오케스트레이터는 각 세션에서 넘어온 결과를 수집하고 하나의 최종 작업물로 통합한다.

실무 연구에서는 2~5개의 병렬 에이전트가 가장 효율적인 것으로 나타난다. 이 범위를 넘으면 에이전트 조율 비용이 병렬화의 이점을 상쇄하기 시작한다. 태스크가 매우 독립적으로 격리된 경우에만 더 많은 에이전트를 운용할 의미가 있다.

에이전트 사이의 메시지는 형식을 통일해 두는 편이 낫다. JSON 스키마로 태스크 지시, 결과 보고, 오류 알림을 구분하면 수신 측이 메시지의 목적을 일관되게 해석할 수 있다. localhost 전용 통신이라도 엔터프라이즈 환경에서는 브로커 포트에 별도의 접근 제어를 설정하는 것이 권장된다.

구현·리뷰·테스트를 세션 사이에 연결하기

코드 리뷰는 역할 분리의 효과가 분명한 사례다. 코드 생성 세션 A가 기능 구현을 마친 뒤 diff를 리뷰 세션 B에 보낸다. B는 변경 내용을 분석해 리뷰 의견을 반환하고, A는 이를 반영한 뒤 테스트 세션 C에 수정 완료를 알린다. C가 실행한 테스트 결과는 A와 B에 브로드캐스트할 수 있다.

디버깅에서도 같은 연결 방식을 쓸 수 있다. 프론트엔드에서 발생한 오류 로그를 담당 세션이 백엔드 세션에 보내면, 백엔드 세션은 API 응답 이상 여부를 확인해 원인을 좁힌다. 서로 다른 계층의 컨텍스트는 분리한 채 조사에 필요한 증거만 주고받는 흐름이다.

LangGraph·CrewAI와 선택 기준 비교

claude-peers, LangGraph, CrewAI는 모두 여러 에이전트를 다루지만 해결하려는 범위가 다르다.

항목	claude-peers	LangGraph	CrewAI
대상 에이전트	Claude Code 인스턴스	범용 LLM 에이전트	범용 LLM 에이전트
통신 방식	MCP 프로토콜 + HTTP	그래프 상태 공유	역할 기반 태스크 위임
오케스트레이션	에드혹(ad-hoc) 메시징	방향성 그래프(DAG)	역할 기반 크루(Crew)
설치 복잡도	낮음 (MCP 설정만 필요)	중간	낮음~중간
프로덕션 성숙도	초기 (2025~2026 공개)	높음 (월 3,450만 다운로드)	중간 (월 520만 다운로드)
주요 강점	Claude Code 네이티브 통합	복잡한 조건부 워크플로우	빠른 프로토타이핑
원격 협업	불가 (localhost 한정)	가능	가능
컨텍스트 격리	명시적 메시지만 공유	그래프 상태 공유	태스크 결과 공유

LangGraph는 2026년 기준 프로덕션 멀티에이전트 시스템에서 가장 널리 채택된 프레임워크다. 에이전트를 방향성 그래프의 노드로 표현하고 조건부 분기, 체크포인팅, 인간 개입(human-in-the-loop)을 명시적으로 제어한다. 규제 산업이나 감사 추적이 필요한 환경에서는 작업을 중단했다가 특정 지점부터 재개할 수 있다는 강점이 있다. 반면 간단한 워크플로우에도 60줄 이상의 명령형 코드가 필요한 경우가 많아 진입 장벽이 생긴다.

CrewAI는 역할 기반 팀 구조를 앞세워 빠르게 개발할 수 있다. LangGraph보다 3배 적은 코드로 같은 기능을 구현할 수 있고, 역할이라는 개념도 개발자가 이해하기 쉽다. 다만 동일한 워크플로우에서 토큰 소비량이 LangGraph보다 최대 3배 높게 측정되는 경우가 있어 대규모 프로덕션에서는 운영 비용을 모델링해야 한다.

claude-peers의 초점은 범용 오케스트레이션이 아니라 Claude Code 네이티브 통신이다. 별도의 파이썬 의존성이나 복잡한 SDK를 익히지 않고 MCP 설정 파일을 수정해 도입할 수 있다. Claude Code의 claude/channel 프로토콜을 직접 사용하므로 메시지 지연(latency)도 매우 낮다.

이 차이는 상호 배타적인 선택을 뜻하지 않는다. LangGraph가 전체 워크플로우를 조정하고, 그래프의 각 노드에서 실행되는 Claude Code 인스턴스끼리 claude-peers로 통신하는 하이브리드 구성을 만들 수 있다. CrewAI와의 관계도 마찬가지다.

분산 시스템 관점에서 읽는 claude-peers

브로커 데몬이 피어 등록 정보와 메시지 경로를 관리하는 구조는 분산 시스템의 브로커 패턴에 해당한다. 클라이언트와 서버가 직접 결합하지 않고 중간 계층을 거치므로 위치 투명성(location transparency)을 제공한다.

응답하지 않는 피어를 브로커가 제거하는 동작은 장애 내성(fault tolerance) 설계와 연결된다. SQLite에 상태를 지속적으로 저장하는 구조는 프로세스가 재시작된 뒤에도 상태를 복구할 수 있게 한다.

세션별 MCP 서버의 폴링과 채널 푸시를 결합한 방식은 이벤트 드리븐 아키텍처(EDA)의 변형으로 볼 수 있다. 매 1초 폴링으로 메시지를 확인하므로 준실시간 이벤트 처리 구조에 해당한다.

각 Claude Code 세션을 하나의 독립된 마이크로서비스로 해석하면 claude-peers는 서비스 메시(service mesh)를 단순화한 AI 에이전트 통신 계층과 닮아 있다. 피어 등록은 서비스 디스커버리, 죽은 피어 제거는 헬스체크, 브로커의 전달 기능은 메시지 라우팅에 대응한다.

공식 오케스트레이션과 저수준 통신 계층의 차이

Anthropic은 2026년 Dynamic Workflows를 공개하며 Claude Code의 멀티에이전트 기능을 강화했다. Claude가 복잡한 소프트웨어 엔지니어링 태스크에 맞춰 오케스트레이션 스크립트를 동적으로 생성하고, 대규모 서브에이전트 플릿을 병렬 실행하는 방식이다.

claude-peers는 이 공식 기능과 별도로 개발자가 에이전트 사이의 통신 채널을 직접 설계하고 실험할 수 있는 저수준 계층을 제공한다. 공식 기능이 배치 오케스트레이션에 맞춰져 있다면, claude-peers는 에드혹 메시징과 피어 간 협업에 초점을 둔다.

원격 통신 지원, 보안 강화, 메시지 큐잉은 향후 발전 방향으로 거론된다. MCP 생태계가 성숙하면 이와 비슷한 에이전트 통신 계층이 여러 형태로 등장할 것으로 전망된다.

로컬 머신에서 Claude Code 세션을 나눠 운영하는 팀이라면 claude-peers는 피어 발견과 메시지 교환부터 시작할 수 있는 선택지다. 병렬 구현, 교차 리뷰, 테스트와 디버깅을 하나의 협업 흐름으로 연결하면서도 각 세션의 컨텍스트는 독립적으로 유지한다. 복잡한 상태 관리가 필요할 때는 LangGraph를, 역할 중심의 빠른 구성이 필요할 때는 CrewAI를 함께 고려할 수 있다.