다른 Claude Code 세션에 메시지 보내기
기준일: 2026-10-23
공식 기준: Message your other Claude Code sessions
개요
Cross-session messaging은 한 세션의 Claude가 내 다른 세션으로 메시지를 전달하게 합니다. 한 세션의 변경이 다른 세션의 작업을 깨뜨리면 미리 경고하고, 한 세션이 다른 세션이 막혀 있던 질문의 답을 얻으면 넘겨줍니다. 메시지는 한 Claude가 다른 Claude에게 쓴 텍스트일 뿐이며 대화 기록이나 파일이 아닙니다. 대화 전체를 옮기려면 세션을 resume하세요.
- 요구 버전: macOS·Linux(WSL 2 포함) v2.1.224+, 네이티브 Windows v2.1.234+. 요건을 만족하면 켤 것이 없이 활성입니다.
- 도구는
ListAgents(대상 탐색)와SendMessage(전송)이며 사용자가 직접 호출하지 않습니다. - 대표 사용처: 발견 사항 전달 / 병렬 worktree 조율 / 장시간 작업 상태 수신 / 다른 머신·클라우드 세션 도달.
핵심 개념
| 개념 | 설명 |
|---|---|
| 대상 탐색·전송 | Claude가 ListAgents로 찾고 SendMessage로 전송. 직접 프롬프트로 요청해도 됨 |
@ 멘션 |
@ + 세션 이름 앞글자로 대상 지정 (2.1.232+). 공백 등 특수문자는 @"release notes" |
| 유휴 알림 | SendMessage의 notify_when_idle 입력으로 상대 세션이 다음에 유휴/종료될 때 1회 알림 (2.1.236+, 양쪽) |
| 수신 제어 | crossSessionInbound: accept / hold / refuse |
| 교차 머신 승인 | isolatePeerMachines: true면 다른 머신 전송 전에 승인 요구 |
| 전달 경로 | 같은 머신은 per-session 소켓(Anthropic 서버 미경유), 다른 머신·클라우드는 Anthropic 서버 경유 |
| inbox 소켓 | 환경 변수 CLAUDE_CODE_MESSAGING_SOCKET, CLAUDE_CODE_MESSAGING_TOKEN |
상세
다른 세션에 메시지 보내기
Claude는 필요를 느끼면 스스로 보낼 수 있고 프롬프트로 요청할 수도 있습니다. 아래는 사용자가 입력하는 프롬프트 예시입니다(Claude가 실제 메시지 문구를 직접 씁니다).
Ask the session running in my other terminal whether the migration finished
Explain what we just did to the session working on the payments API
대상을 직접 지정하려면 @를 입력하고 이름 앞글자 후 typeahead에서 선택합니다(@api-worker 형태로 삽입되고 Claude에 어느 세션인지 알려 줌).
Let @api-worker know the schema migration finished
typeahead는 이 머신의 다른 라이브 세션을 보여줍니다. 이 머신 밖의 클라우드/Remote Control 세션은 Claude가 먼저 세션을 나열하거나 메시지를 보낸 뒤에야 typeahead에 나타나므로 먼저 목록을 요청하세요. 같은 이름에 라이브 세션이 여러 개면 Claude가 어느 쪽인지 묻습니다.
전달 방식
수신 Claude는 활성 턴 중 도구 호출 사이에 메시지를 읽고(실행 중 도구는 중단되지 않음), 유휴면 Claude Code가 메시지로 새 턴을 시작합니다. 메시지는 평문으로 도착하며 @로 언급한 파일·MCP 리소스를 첨부하지 않습니다(Claude가 자기 도구로 열 수는 있으나 해당 세션의 권한을 따름).
전송이 거부되는 경우:
- 메시지가 크기 상한 초과(보내는 세션에서 거부)
- 이 머신 세션으로의 빠른 연속 전송이 그 세션 inbox 수용량에 도달
- 이 머신 밖 세션이 "메시지를 받을 수 없음"으로 표시됨(보내는 세션에서 거부)
- 이 머신의 회신 대상이 안전 검사(심볼릭 링크 대상 등)에 실패
수신 세션은 도착 메시지를 자체 inbound 제어로 검사해 세 결과 중 하나를 냅니다. Delivered(Claude에 전달) / Held(보류, 승인하거나 이후 모드·설정 변경이 허용할 때까지 미전달) / Refused(전달 없이 폐기). 전달된 메시지는 직접 입력한 프롬프트처럼 사용량에 집계되고, 수신 Claude는 SendMessage로 회신할 수 있습니다(클라우드 세션 등 예외 있음).
권한 경계는 세션별입니다. Claude는 자기 세션에서 거부·차단되었거나 자기 권한 설정이 막을 동작을 다른 세션에 요청하지 않고 사용자에게 돌려보내도록 지시받으며, 수신 측의 자체 권한 프롬프트와 규칙도 그대로 적용됩니다.
다른 세션이 유휴가 되면 알림 받기 (2.1.236+)
이 머신의 한 세션에 "다음에 유휴가 되거나 종료할 때 알림 1회"를 요청합니다. 유휴는 큐에 아무것도 없이 턴을 마친 상태입니다. 양쪽 세션 모두 2.1.236 이상이어야 합니다.
Tell me when the migration session finishes what it's working on
Claude는 SendMessage의 notify_when_idle 입력으로 구독합니다. 단독이면 감시되는 세션에서 턴이나 토큰을 쓰지 않고 구독하며 이미 유휴면 즉시 알립니다. 메시지에 붙이면 메시지를 먼저 전달하고 알림은 나중에 보냅니다. 감시되는 세션에는 다른 프로세스가 다음 유휴 시 알림을 요청했다는 줄이 표시되고, 요청한 세션에는 감시 세션 이름의 알림 줄(턴 종료 시각, 한 줄 상태 포함 가능)이 표시되며 요청 측이 유휴면 새 턴이 시작됩니다.
제한: 12시간 안에 알림이 없으면 구독을 버리고 Claude에 알립니다. 양쪽 inbound 제어가 알림에도 적용되어 한쪽이라도 refuse면 아무것도 도착하지 않고(감시 측은 기록·응답 없이 폐기, 요청 측이 refuse면 구독 자체를 안 함), hold면 감시 측은 한 줄 상태를 빼고 요청 측은 알림을 transcript에만 표시하고 Claude에 전달하지 않습니다. 메인 대화의 Claude만 이 머신의 내 세션에 대해서만 구독할 수 있고, teammate·subagent·이 머신 밖 세션 등 다른 대상에 요청하면 첨부된 메시지까지 통째로 거부됩니다.
Claude가 닿을 수 있는 세션 확인
/list-agents(또는 /peers)로 직접 확인합니다. 첫 줄(있으면)은 이 세션의 자기 이름이고 아래 행은 닿을 수 있는 세션입니다.
- Subagents: 현재 세션 안에서 도는 에이전트
- Teammates: 이 세션의 agent team 팀원
- 내 다른 로컬 세션: 같은 머신의 세션(백그라운드 세션 포함). inbox 소켓을 바인드한 세션만 표시
- 내 클라우드 세션: 이 세션이 Remote Control에 연결된 동안 표시
- 다른 머신의 Remote Control 세션: Remote Control에 연결된 동안
Remote Control라벨로 표시. 연결이 끊기면 상태가offline
이 세션이 Remote Control에 연결돼 있으면 로컬 세션 정보 일부가 출력에서 가려집니다(Claude 자신이 보는 것은 달라지지 않음). 각 로컬 세션의 작업 디렉터리, 사람에게 귀속시킬 수 없는 세션 이름((unnamed session)으로 표시), 그리고 이 터미널에서 --name 또는 /rename으로 직접 입력하지 않은 경우 자기 이름 줄. 가려진 항목이 있으면 출력 끝에 안내 문구가 나옵니다. 사용되지 않은 이름으로 /rename하면 그 세션 이름이 출력에 나타납니다.
세션은 /rename이나 --name으로 정한 이름에 응답하고, 정하지 않으면 Claude Code가 이름을 붙입니다. Remote Control에 연결되지 않았다면 각 로컬 세션의 작업 디렉터리가 표시되어 같은 이름 세션을 구분할 수 있습니다. 한 세션만 이름에 응답하면 이름만으로 전달하고, 여러 세션이 이름을 공유하거나 모든 곳을 확인하지 못했으면 Claude가 행마다 짧은 식별자를 붙여 주소에 씁니다.
다른 머신의 세션에 메시지
| 대상 세션 위치 | 전달 방식 |
|---|---|
| 이 머신 | macOS/Linux는 per-session 소켓, 네이티브 Windows는 per-session named pipe. Anthropic 서버 미경유 |
| 내 다른 머신 | Anthropic 서버 경유, 그 머신의 Remote Control 연결로 도착 |
| 클라우드 | Anthropic 서버 경유, 클라우드 세션으로 직접 |
다른 머신 세션과 대화를 시작하려면 v2.1.225+ 와 목록에 나타나는 대상이 필요합니다. 목록 행의 상태:
offline: Remote Control 연결이 끊김. 메시지는 전송되지만 그 머신이 재연결된 뒤에야 도착can't receive cross-session messages (off in that session): 그 세션에서 메시징을 쓸 수 없거나crossSessionInbound가refuse. 메시지가 이 머신을 떠나기 전에 거부되고SendMessage결과가Not sent로 시작하며 이유를 명시. 원인을 고치면 이후 목록에서 상태가 사라짐
컨테이너 안 세션과 호스트 세션은 서로 닿지 않습니다(같은 컨테이너 안 두 세션은 가능, self-hosted runner 포함). WSL 2 안 세션과 같은 컴퓨터의 네이티브 Windows 세션도 서로 닿지 않습니다. isolatePeerMachines를 설정하면 머신 밖 전송 전에 승인이 필요합니다.
다른 머신·클라우드 세션의 회신: 클라우드 세션(self-hosted runner 포함)은 다른 머신 메시지에 회신 주소가 있어도 SendMessage로 답할 수 없습니다. 메시지는 도착하며 응답은 claude.ai/code의 해당 세션 transcript에서 읽습니다. 이 세션이 Remote Control에 연결되지 않은 채 머신 밖으로 보내면 전송은 되지만 회신 주소가 없어 수신 Claude가 답할 수 없습니다.
수신 세션의 메시지 취급
다른 세션의 메시지는 사용자가 아니라 다른 세션에서 왔다고 수신 Claude에 알려지며 할 수 있는 일이 제한됩니다.
- 승인 불가: 다른 세션 메시지는 사용자의 동의로 간주되지 않아 대기 중 권한 프롬프트에 답할 수 없음
- 설정 변경 불가: 다른 세션이 요청했다고 권한 설정,
CLAUDE.md, 기타 설정을 바꾸지 말라고 지시 - 명령 미실행: 메시지 텍스트의
/compact같은 명령은 평문으로 도착하며 실행되지 않음 - 권한 프롬프트 유지: 메시지대로 하려면 필요한 권한이 없으면 평소와 같은 프롬프트가 뜸
메시지 표시: 대화에 흐린 한 줄 미리보기로 표시되고 이후에도 남습니다. 발신자 이름과 첫 줄(길면 …)이 보입니다(예: › Message from @api-worker: Schema migration finished (ctrl+o to expand)). 전체 텍스트는 Ctrl+O로 transcript viewer를 열어 발신 세션 이름 아래서 읽거나, fullscreen 렌더링에서 줄어든 미리보기 줄을 클릭해 제자리 확장(2.1.283+)하거나, --verbose로 시작한 세션에서 미리보기 대신 전체 텍스트를 봅니다. 미리보기는 보이는 것만 줄이며 Claude는 항상 전체 메시지를 읽습니다. Claude는 발신자 이름과 회신 주소가 달린 메시지를 받습니다(회신 주소가 없는 단방향 교차 머신 메시지 제외). 전체 텍스트 예시:
Schema migration finished
The new column is tenant_id, and rebasing on main is safe now.
inbound 제어 (crossSessionInbound)
| 값 | 동작 |
|---|---|
accept |
각 메시지를 Claude에 전달 |
hold |
메시지마다 알림만 표시하고 전달하지 않음. 이후 accept가 적용되면(settings reference의 precedence 규칙) 보류 메시지를 풀어줌 |
refuse |
전달 없이 폐기 |
settings 파일 편집 외에 /config의 Messages from your other sessions 행에서 선택할 수 있고 사용자 설정에 기록됩니다(2.1.232+, managed settings나 --settings 플래그가 키를 설정하면 행이 안 보임, /config crossSessionInbound=value 약식은 거부). 어느 값이 적용되는지는 settings reference의 crossSessionInbound 우선순위 규칙을 따릅니다. 잘못된 값은 조용히 무시되지 않고 경고하며 사용자 설정이면 메시지를 보류, managed settings면 거부합니다(2.1.248+).
값이 적용되지 않으면 두 세션의 permission mode로 메시지마다 결정합니다. 권한 프롬프트를 우회하는 세션(bypassPermissions; bypass 가능한 대화형 터미널의 plan mode도 우회로 취급)을 한 클래스, 나머지(auto, acceptEdits, dontAsk 포함)를 다른 클래스로 묶습니다.
- 수신 세션이 권한을 묻는 경우: 모든 메시지 전달. 발신 세션이 스스로 우회라고 밝힐 때만 승인 대기로 보류
- 수신 세션이 우회하는 경우: 모든 메시지를 승인 대기로 보류. 발신 세션도 우회라고 밝힐 때만 전달
기본이 대화형 터미널 세션에서 메시지를 보류하면 발신자와 미리보기가 든 승인 대화상자가 열립니다. Approve는 그 메시지 1건 전달, Deny나 닫기는 폐기, dialogExpiry(기본 5분) 안에 응답하지 않으면 닫고 폐기합니다. 터미널이 붙지 않은 백그라운드 세션은 마감 후에도 대화상자를 열어 두고 attach 뒤 한 마감 주기 동안 응답이 없으면 닫고 폐기합니다. 보류 중 permission-mode 클래스가 바뀌면 inbound 규칙을 다시 적용해 이제 허용되는 메시지를 전달하고 알립니다. VS Code 확장·Desktop 앱 세션은 대화상자를 못 띄우므로 같은 마감까지 보류 메시지를 유지합니다. 최대 100건을 보유하고 넘으면 가장 오래된 것을 버립니다. (2.1.287+ 보류 메시지 프롬프트는 메시지를 점선 사이에 보여줌)
비대화형 세션: claude -p 세션도 대화형처럼 inbox 소켓을 바인드해 장기 -p 워커가 메시지를 받고 목록에 나타납니다. bare mode로 시작하면 소켓을 바인드하지 않아 수신할 수 없고 에이전트 목록에도 안 나타납니다. -p 세션은 승인 대화상자를 못 띄우므로 기본이 메시지를 보류하면 같은 dialogExpiry(기본 5분) 마감까지 보관합니다. 마감 전에 모드·설정 변경이 허용하면 전달하고, 마감 후에는 폐기하며 닿을 수 있는 발신자에게 만료로 보고합니다. dialogExpiry를 "never"로 두면 기본 보류 메시지를 세션 종료까지 유지하고, 명시적 hold로 보류한 메시지는 만료되지 않으며 이후 accept가 적용되면 전달합니다. -p 워커가 무인으로 메시지를 받으려면 --settings 값에 crossSessionInbound: accept를 두고 시작하세요(사용자 설정의 accept도 되지만 모든 세션에 적용).
세션의 inbox 소켓
예상한 세션이 에이전트 목록에 없거나, 스크립트·hook에서 세션에 메시지를 넣으려 하거나, 샌드박스 명령이 소켓에 닿지 못할 때 읽는 절입니다. 메시징이 켜진 세션마다 Claude Code가 inbox 소켓을 바인드합니다(macOS/Linux는 WSL 2 포함 Unix domain socket, 네이티브 Windows는 named pipe). --restricted / CLAUDE_CODE_RESTRICTED=1 세션은 소켓을 열지 않습니다(2.1.290 수정).
- 경로 확인:
/status의Peer address행(uds:접두사), 또는 hook·Bash 명령에CLAUDE_CODE_MESSAGING_SOCKET환경 변수로 export(메시징이 켜진 세션은SessionStart포함 모든 hook보다 먼저 export) - 보안: macOS/Linux는 소켓을 OS 사용자로 제한하고, 네이티브 Windows는 해당 사용자만 읽을 수 있는 키로 연결마다 먼저 인증. 공유 머신에서 다른 사용자 세션은 전달할 수 없음
- 디렉터리: macOS/Linux에서 다른 사용자가 소유한 디렉터리 등 받아들일 수 없는 곳에는 소켓을 만들지 않고
/tmp/cc-socks-<uid>를 씁니다. 어느 디렉터리도 안 되면 inbox 없이 실행되며 알림이 뜨고/status가unavailable과 이유를 표시,--debug로그에 전체 거부 내용이 남음
세션별 토큰은 CLAUDE_CODE_MESSAGING_TOKEN으로 export됩니다. 자기 세션 소켓에 게시하는 스크립트는 연결의 첫 줄로 {"type":"auth","token":"<token>"}를 보낼 수 있습니다.
- macOS/Linux(WSL 2 포함): 첫 줄은 선택
- 네이티브 Windows: 첫 줄 필수(유효한 auth 줄이 아니면 연결을 닫고 아무것도 전달 안 함)
보낼 메시지가 준비된 뒤에 연결을 여세요. 30초 안에 완전한 한 줄을 보내지 않으면 연결을 닫습니다(2.1.243+). 느린 명령은 출력을 먼저 캡처한 뒤 연결합니다.
소켓으로 오는 메시지도 다른 peer 메시지와 같은 inbound 제어를 거치며 예외 하나와 전제 하나가 있습니다.
- 자기 자식 메시지: 적용되는
crossSessionInbound값이 없으면, 세션 자신의 자식 프로세스(자기 소켓에 되돌려 게시하는 hook·Bash 명령)에서 왔다고 검증되는 메시지는 전달합니다. Linux(WSL 2 포함)는 이미 종료한 자식도 프로세스 증거로 검증 가능, macOS는 게시 프로세스가 아직 실행 중일 때만, PID 1로 Claude Code를 실행하는 컨테이너와 네이티브 Windows는 프로세스 증거가 없습니다. 증거가 없으면(macOS에서 게시 프로세스 종료 후, PID 1 컨테이너) 연결을 연 auth 줄에 세션의CLAUDE_CODE_MESSAGING_TOKEN을 보낸 자식을 검증하고, 네이티브 Windows는 이 토큰이 유일한 검증 방법입니다. 어느 쪽도 검증하지 못하면 권한 클래스를 주장하지 않는 다른 메시지처럼 취급되어 권한 프롬프트를 우회하는 세션은 승인 대기로 보류합니다. - 샌드박스 세션: Bash 명령이 샌드박스 안에서 소켓에 닿을 수 있는지는
sandbox.network.allowAllUnixSockets,sandbox.network.allowUnixSockets로 제어합니다.
제한: 교차 머신 승인과 끄기
교차 머신 메시지 승인 요구: isolatePeerMachines를 true로 두면 이 머신 밖 세션으로 가는 모든 SendMessage 전에 명시적 승인을 요구합니다.
{
"isolatePeerMachines": true
}
bypassPermissions에서도 승인을 묻습니다. 어느 settings scope든 true가 적용되므로 체크인된 프로젝트 파일은 요구를 켤 수 있어도 끌 수는 없습니다. 같은 머신 세션 간에는 묻지 않습니다.
메시징 끄기: 수신과 송신은 별개 제어입니다.
- 수신 중지:
crossSessionInbound를refuse로. 프로젝트/로컬 설정의refuse는 다른 모든 소스보다 우선하고, 사용자 설정의refuse는 managed settings나--settings가 값을 정하지 않은 경우에 적용 - 송신·나열 중지:
SendMessage와ListAgents에 대한 permission deny 규칙 추가(둘 다 specifier 없이 도구 이름만)
관리자는 managed settings에서 조직 전체의 양쪽을 끌 수 있습니다.
{
"permissions": {
"deny": ["SendMessage", "ListAgents"]
},
"crossSessionInbound": "refuse"
}
이 경우에도 Claude Code는 inbox 소켓을 바인드하지만 도착하는 모든 메시지를 Claude에 전달 없이 폐기합니다. SendMessage deny는 subagent·agent team 팀원에 대한 메시징도 제거합니다(같은 도구를 쓰기 때문). 거부하는 세션은 자기 /status나 같은 머신 다른 세션의 목록에서 눈에 띄는 변화가 없으므로, 확인은 상태가 아니라 해당 세션에 적용되는 settings 파일을 보세요.
가용성
v2.1.224+ (macOS, Linux, WSL 2), 네이티브 Windows는 v2.1.234+. 이후는 OS, 프로바이더, 구성에 따라 다릅니다.
- 같은 머신 세션: Amazon Bedrock, Claude Platform on AWS, Google Cloud Agent Platform, Microsoft Foundry를 포함한 모든 프로바이더와 feature-flag fetching을 끈 세션에서도 가능. 이 경우는 v2.1.248+ 필요. 소켓으로 전달되며 Anthropic 서버를 거치지 않음. 수신을 막으려면
crossSessionInbound: refuse - 이 머신 밖 세션: Remote Control에 연결된 세션(활성 인증이 claude.ai 로그인이어야 하며 나머지 Remote Control 요건 충족)에서 클라우드·다른 머신 세션을 찾음. API 키나 Bedrock/Claude Platform on AWS/Google Cloud Agent Platform/Microsoft Foundry에서는 찾을 수 없음
/list-agents(또는 /peers)로 확인합니다. 인식되지 않으면 세션에 기능이 없는 것이므로 claude --version부터 요건을 점검합니다. 동작하는데 전송이 도착하지 않으면 더 좁은 원인입니다.
- permission deny 규칙이
SendMessage·ListAgents도구를 제거 - 수신 세션의 inbound 제어가 보류하거나 폐기
- 클라우드 세션 누락: 이 세션이 Remote Control에 연결된 동안만 표시
- 다른 머신 세션 누락: 그쪽도 Remote Control로 실행 중이고 이 세션도 연결돼 있어야 표시
- 다른 머신 세션
offline: 전송되지만 재연결 후 도착 - 클라우드/다른 머신 세션
can't receive cross-session messages: 이 머신을 떠나지 않으며 결과가Not sent로 시작 - 오래된 클라우드·다른 머신 세션 누락: 세션 목록을 최신순으로 제한된 페이지 수만큼 읽어서 그 뒤로 밀린 세션은 이름으로 메시지할 수 없음
메시징이 있는 세션의 /status에는 Peer address 행이 자기 inbox 주소를, inbox를 못 만들었으면 unavailable과 이유를 보여줍니다. 최근 변경: 2.1.288에서 상대 세션이 보류한 메시지를 전달됨으로 보고하던 문제가 수정되어 전달되지 않았다고 세션 이름과 함께 알립니다. 2.1.309에서 ctrl+o가 아직 전달 대기 중인 다른 에이전트·세션 메시지를 "waiting" 표시와 함께 전체로 보여줍니다.
한계
- 평문만: 세션 간에는 평문만 전송. 구조화된 agent team 프로토콜 메시지는 팀 안에 머뭄
- 같은 머신 메시지 크기 상한: 직렬화 후 약 100만 자를 넘으면 거부(정확한 크기를 명시, 수신 세션에는 아무것도 가지 않음)
- 한 세션으로의 빠른 연속 전송은 발신 측에서 거부: 한 세션 inbox 수용량에 도달하면 이후 전송을 거부하고 Claude에게 나머지를 한 메시지로 묶거나 기다리라고 안내
- 메시지 루프 제한: 수신 세션이 발신자별 반복 메시지를 rate-limit하고, 짧은 시간 안에 오는 동일 반복을 버리며, Claude가 읽을 수락 메시지를 최대 50건까지 큐잉하므로 두 세션 간 루프는 스스로 멈춤