Claude Code를 여러 터미널에 띄우면 사람이 세션 사이의 메시지를 옮기게 됩니다. 한 세션은 라이브러리를 고치고 다른 세션은 앱을 고치는데, 둘 사이의 상태는 사람이 복사해서 붙여 넣습니다. 에이전트는 병렬로 일하지만 메시지 라우터 역할은 사람이 맡습니다.
Claude Code Cross-Session Messaging ↗을 쓰면 독립적으로 실행 중인 Claude Code 세션끼리 텍스트 메시지를 주고받습니다. 한 세션에서 발견한 결정·상태·주의사항을 다른 세션으로 바로 넘길 수 있습니다.
이 기능은 세션 전체를 합치거나 히스토리를 공유하지 않습니다. 필요한 순간에 한 Claude가 다른 Claude에게 요약된 텍스트를 보내는 협업 레이어입니다.
ClaudeDevs 공식 X 발표 ↗는 이 기능을 “세션끼리 메시지를 보낼 수 있다”는 한 문장으로 소개합니다. 아래 영상에서는 사용자가 다른 세션에 다시 설명하지 않습니다. Claude가 요약을 보내고, 수신 세션이 작업 중간에 받아 처리합니다.
2026-08-09에 확인한 Claude Code Cross-Session Messaging 공식 문서, ClaudeDevs 공식 X 발표, Claude Code v2.1.224를 기준으로 합니다.
이 글에서 다루는 내용은 세 가지입니다.
- Cross-Session Messaging이 무엇을 주고받는가
- Agent Teams, Agent View, Channels와 무엇이 다른가
- 실제 병렬 작업에서 무엇을 설정하고 확인해야 하는가
왜 필요한가?
Claude Code는 이미 여러 병렬 작업 기능을 제공합니다. Agent View는 여러 백그라운드 세션을 한 화면에서 관리합니다. Agent Teams에서는 Claude가 직접 팀원을 만들고 조율합니다. Channels는 Telegram, Discord, 웹훅 같은 외부 이벤트를 세션으로 밀어 넣습니다.
이 셋으로 해결되지 않는 경우가 있습니다. 사용자가 여러 독립 세션을 띄워두고, 각 세션이 서로 다른 디렉터리나 worktree에서 일할 때입니다. 한 세션이 “이 변경이 다른 세션의 작업을 깨뜨릴 수 있다”는 사실을 알아도, 예전에는 사람이 그 내용을 옮겨야 했습니다.
공식 문서 ↗가 드는 대표 사례는 네 가지입니다. finding handoff, 병렬 worktree 조율, 긴 작업 상태 확인, 다른 머신이나 웹 세션에서 온 메시지에 대한 reply입니다. 이 기능은 모든 컨텍스트를 공유하는 대신 작업 중간에 필요한 신호를 전달합니다.
동작 방식: ListAgents와 SendMessage
Cross-Session Messaging은 한 Claude Code 세션에서 다른 세션으로 텍스트 메시지를 보내는 기능입니다. 공식 문서 ↗에 따르면 Claude는 ListAgents로 도달 가능한 세션을 찾고, SendMessage로 대상 세션에 메시지를 보냅니다.
메시지는 텍스트 조각이고, 대화 히스토리나 파일은 넘어가지 않습니다. 전체 대화나 컨텍스트를 이어가야 한다면 메시징이 아니라 session resume ↗을 써야 합니다.
sequenceDiagram
participant A as 세션 A<br/>라이브러리 작업
participant S as Claude Code<br/>세션 메시징
participant B as 세션 B<br/>앱 작업
A->>S: SendMessage<br/>"타입 변경 완료, 앱 쪽 import 수정 필요"
S->>B: 텍스트 메시지 전달
B->>B: 현재 작업 맥락에서 반영 여부 판단
B-->>S: reply<br/>"앱 쪽 수정 끝, 테스트 통과"
S-->>A: 답장 전달수신 세션이 실행 중인 도구를 강제로 끊지는 않습니다. 공식 문서는 메시지가 활성 turn 중에는 tool call 사이에 읽히고, 세션이 idle이면 새 turn으로 시작된다고 설명합니다. 메시지는 작업을 중단시키지 않고, 다음 안전한 지점에 작업 정보를 끼워 넣습니다.
로컬은 소켓, 원격은 Remote Control
같은 머신에서 실행 중인 세션끼리는 세션별 inbox socket을 통해 메시지가 전달됩니다. 공식 문서의 전송 표 ↗는 같은 머신 메시지가 Anthropic 서버를 거치지 않고 per-session socket으로 이동한다고 설명합니다.
다른 머신이나 Claude Code on the web 세션과의 메시지는 Remote Control 연결을 통해 Anthropic 서버를 거칩니다. 이 경우 버전 차이를 확인해야 합니다. Cross-Session Messaging 본문은 원격 세션을 reply-only로 설명합니다. 반면 Claude Code v2.1.225 changelog ↗는 SendMessage가 Remote Control 세션도 이름으로 찾아 새 대화를 시작할 수 있다고 적습니다.
| 대상 세션 위치 | 전송 방식 | 확인할 점 |
|---|---|---|
| 같은 머신 | 세션별 socket | 새 메시지와 답장, 서버 경유 없음 |
| 다른 내 머신 | Remote Control 경유 | v2.1.225부터 이름 기반 시작 가능 여부 확인 |
| Claude Code on the web | 클라우드 세션으로 전달 | Remote Control 연결 상태와 대상 이름 확인 |
같은 머신의 여러 worktree를 조율하는 용도라면 로컬 메시징으로 충분합니다. 원격 장비나 웹 세션까지 엮는다면 Remote Control 연결 상태와 설치 버전을 같이 확인합니다.
Agent Teams·Agent View·Channels와의 차이
Cross-Session Messaging은 이름 때문에 Agent Teams와 헷갈리기 쉽습니다. 두 기능은 쓰는 상황이 다릅니다.
| 기능 | 적합한 상황 | 핵심 차이 |
|---|---|---|
| Cross-Session Messaging | 사용자가 이미 띄운 독립 세션끼리 필요한 말만 주고받을 때 | 세션은 독립 유지, 텍스트만 전달 |
| Agent Teams | Claude가 팀원을 만들고 작업 목록과 메시지를 함께 관리할 때 | 하나의 팀 구조 안에서 조율 |
| Agent View | 여러 백그라운드 세션을 한 화면에서 보고 개입할 때 | 사람이 세션 상태를 관찰하고 attach |
| Channels | 외부 이벤트를 Claude Code 세션으로 push할 때 | Telegram, Discord, 웹훅 같은 외부 입력 |
예를 들어 한 저장소를 세 worktree로 나눠 각각 Claude Code를 열어두었다면 Cross-Session Messaging을 씁니다. 처음부터 “리서처, 구현자, 리뷰어 팀을 만들어서 이슈를 처리해줘”라고 맡긴다면 Agent Teams가 맞습니다.
worktree는 git worktree가 에이전트 시대에 다시 중요해진 이유에서 다뤘습니다. worktree가 파일 충돌을 줄인다면, Cross-Session Messaging은 그 위에서 “어떤 변경이 누구에게 영향을 주는지”를 알려줍니다.
보안 경계
메시지는 권한을 대신하지 않습니다. 공식 문서 ↗에 따르면 다른 세션에서 온 메시지는 사용자 동의로 간주되지 않고, permission prompt를 승인할 수 없습니다. 설정이나 CLAUDE.md 같은 구성을 바꾸라는 요청도 그대로 수행하지 않습니다.
명령어처럼 보이는 텍스트도 그냥 텍스트로 들어옵니다. 예를 들어 메시지 본문에 /compact 같은 내용이 있어도 Claude Code가 그것을 명령으로 실행하지 않습니다.
관리와 차단도 설정으로 분리되어 있습니다. 수신은 crossSessionInbound로 accept, hold, refuse를 정할 수 있고, 송신과 목록 조회는 permission deny rule에서 SendMessage, ListAgents를 막는 방식으로 제어합니다. 다른 머신으로 나가는 메시지에 승인을 요구하려면 isolatePeerMachines를 true로 둘 수 있습니다.
{
"isolatePeerMachines": true,
"crossSessionInbound": "hold",
"permissions": {
"deny": ["SendMessage", "ListAgents"]
}
}위 설정 조각은 제어 지점을 한곳에 모아 보여줍니다. 실제 운영에서 모두 한 번에 쓸 필요는 없습니다. 조직 환경이라면 “받기”, “보내기”, “다른 머신으로 나가기”를 별도 정책으로 정합니다.
시작 전 확인할 것
공식 문서 기준 Cross-Session Messaging은 Claude Code v2.1.224 이상에서 동작합니다. macOS와 Linux, WSL 2의 Linux에서 사용할 수 있습니다. native Windows에서는 제공되지 않고, Amazon Bedrock, Claude Platform on AWS, Google Cloud Agent Platform, Microsoft Foundry 환경에서도 사용할 수 없습니다.
세션에서 기능이 켜졌는지 확인하려면 /list-agents 또는 /peers를 입력합니다. 명령이 인식되지 않으면 버전이나 환경 요건부터 확인합니다. 목록은 보이는데 메시지가 도착하지 않는다면 SendMessage/ListAgents deny rule, 수신 세션의 crossSessionInbound, Remote Control 연결 상태를 확인합니다.
/list-agents메시징이 되는 세션에서는 /status에 Peer address 행도 표시됩니다. 비대화형 claude -p 세션도 inbox socket을 바인딩할 수 있습니다. 반면 bare mode는 socket을 만들지 않아 목록에 나타나지 않습니다.
메시징이 쓰이는 작업 흐름
첫 번째는 병렬 worktree 작업입니다. 예를 들어 ui-components 세션이 컴포넌트 API를 바꾸고, dashboard-app 세션이 그 컴포넌트를 소비하고 있다면, API 변경 사실을 사람이 옮기지 않아도 됩니다. 한 세션이 변경 요약을 보내고, 다른 세션은 자기 맥락에서 반영 여부를 판단합니다.
두 번째는 긴 작업 상태 확인입니다. 마이그레이션이나 대규모 테스트를 맡긴 세션이 따로 있고, 다른 세션에서 전체 진행을 보고 있다면 “끝났는지 확인해줘”라고 묻거나, 완료 시 요약을 보내게 할 수 있습니다.
세 번째는 결정 전파입니다. 한 세션에서 “이번 리팩터링은 호환성 때문에 기존 API를 유지한다”고 정했다면, 같은 저장소의 다른 세션들에게 그 결정을 알려 불필요한 반대 방향 수정을 줄일 수 있습니다.
메시지를 너무 많이 보내면 노이즈가 됩니다. 공식 문서에 따르면 동일 메시지 반복과 메시지 루프는 제한됩니다. 그래도 보낼 메시지는 “다른 세션의 판단을 바꿀 정보”로 한정합니다.
마무리
지금까지는 여러 Claude Code 세션을 띄우면 사람이 컨텍스트 라우터가 됐습니다. Cross-Session Messaging으로 그중 일부를 Claude가 직접 처리합니다.
이 기능은 히스토리를 공유하지 않고, 권한을 위임하지 않으며, 자동 오케스트레이터도 아닙니다. 독립 세션들이 필요한 순간에 짧은 텍스트를 주고받게 합니다. 병렬 worktree, 장기 실행 작업, 여러 터미널을 쓰는 개발 흐름에서는 이 정도로도 사람이 옮기던 메시지가 줄어듭니다.
관련 글:
- Claude Code Agent View — 여러 세션을 한 화면에서 보고 개입하는 방식
- Claude Code Agent Teams — Claude가 팀원을 만들고 조율하는 방식
- Claude Code Channels — 외부 이벤트를 세션으로 push하는 방식
- 에이전트 시대에 git worktree가 다시 뜨는 이유 — 병렬 작업의 파일 격리 바닥