다른 Claude Code 세션에 메시지 보내기

다른 Claude Code 세션에 메시지 보내기

Claude가 이 머신의 다른 Claude Code 세션을 나열하고 메시지를 보내게 하고, 다른 머신이나 웹에 있는 내 세션까지 닿게 할 수 있어요. 한 세션의 변경이 다른 세션이 짓는 것을 깨뜨릴 때, 내가 눈치채기 전에 그 세션에 경고할 수 있죠. 이 문서에서는 세션 간 메시지 전달, 수신 제어, 플랫폼별 가용성과 한계를 다룹니다.

출처: 공식문서

본문

참고: 크로스 세션 메시징은 macOS와 Linux(WSL 2 내부의 Linux 포함)에서 Claude Code v2.1.224 이상, 네이티브 Windows에서 v2.1.234 이상이 필요해요. 세션이 요구 사항을 충족하면 메시징은 켤 것 없이 켜져 있어요. 프로바이더 요구 사항과 세션이 그것을 가졌는지 확인하는 법은 가용성을 보세요.

크로스 세션 메시징은 Claude가 내 Claude Code 세션 하나에서 다른 하나로 메시지를 전달하게 해요. 한 세션의 변경이 다른 세션이 짓고 있는 것을 깨뜨리면, Claude가 내가 알기 전에 그 세션에 경고할 수 있어요. 한 세션이 다른 세션이 막힌 질문을 해결하면 Claude가 답을 건너 보낼 수 있죠.

메시지는 한 Claude가 다른 Claude에게 쓰는 텍스트 조각이지, 발신자의 대화 기록이나 파일이 아니에요. 전체 대화나 그 컨텍스트를 옮기려면 세션 재개를 대신 하세요.

Claude는 이를 위해 두 도구를 써요. ListAgents로 닿을 수 있는 에이전트를 발견하고, SendMessage로 이름으로 그중 하나에 메시지를 전달해요. 같은 SendMessage 도구로 Claude는 단일 세션이나 팀 안의 서브에이전트와 에이전트 팀 팀원에게도 메시지를 보낼 수 있어요. 이 페이지는 독립 세션 사이의 메시지를 다뤄요.

크로스 세션 메시징을 언제 쓰나요

내 세션 중 하나가 다른 세션이 작업 중간에 필요한 것을 갖고 있을 때 메시징을 쓰세요. Claude는 필요를 볼 때 스스로 메시지를 보낼 수 있고(다른 세션이 하는 작업에 영향을 주는 변경을 한 뒤처럼), 직접 보내라고 할 수도 있어요. 흔한 경우는 다음과 같아요.

  • 조사 내용 넘겨주기: 한 세션이 파괴적 변경을 발견하거나 결정을 내리면 Claude가 영향받은 영역을 작업하는 세션을 위해 요약해요. 내가 거기서 다시 설명하지 않아도 되죠.
  • 병렬 워크트리 조율: 세션이 별도 워크트리에서 같은 저장소를 작업할 때 Claude가 뭐가 랜딩됐는지 다른 세션에 알려줄 수 있어요.
  • 오래 도는 작업에서 상태 받기: 마이그레이션이나 테스트 실행이 내가 보고 있는 세션에 다시 보고하게 하거나, 거기서 직접 물어봐요. 그 세션이 이 머신에 있으면 Claude가 다음에 유휴가 되거나 종료할 때 알림 하나를 요청할 수도 있어요.
  • 머신 간 메시징: 다른 머신이나 웹에 있는 내 세션에 닿기.

메시징은 내가 시작하고 조종하는 독립 세션 사이에 쓰세요. Claude Code는 여러 세션을 실행·도달하는 다른 각 방식에 전용 기능이 있으니, 하려는 일에 맞게 만들어진 것을 쓰세요.

  • 한 대화를 다른 터미널에서 계속하거나 그 컨텍스트를 새 세션과 공유하려면 세션 재개
  • Claude가 만들고 감독하는 조율된 세션 팀은 에이전트 팀
  • 여러 세션을 한 곳에서 보고 조종하려면 에이전트 뷰
  • 세션끼리 메시징하는 대신 폰·다른 기기에서 직접 조종하려면 리모트 컨트롤
  • CI 결과·챗 메시지 같은 외부 이벤트를 세션으로 밀어 넣으려면 채널

다른 세션에 메시지 보내기

내 세션 중 하나가 다른 세션이 필요한 것(조사 내용, 상태, 결정)을 알게 되면 Claude가 터미널 사이에서 복사 붙여넣기하는 대신 전달해요. Claude는 ListAgents로 대상을 발견하고 SendMessage로 보내므로, 도구를 직접 호출하지 않아요. Claude는 요청 없이도 메시지를 보내기로 결정할 수 있고, 직접 요청할 수도 있어요.

직접 요청하려면 다른 세션이 알거나 하길 원하는 것을 Claude에게 말하세요. 이 예제는 Claude가 보내는 메시지가 아니라 내가 입력하는 프롬프트예요.

Ask the session running in my other terminal whether the migration finished

Claude가 실제 메시지를 직접 쓰므로 내 프롬프트는 내용을 Claude에게 맡길 수 있어요. 이 프롬프트는 문구를 지시하지 않고 요약을 요청하며, Claude가 보내는 것은 달라져요.

Explain what we just did to the session working on the payments API

대상을 직접 지명하려면 프롬프트에서 세션을 언급하세요. 세션 이름의 첫 글자 뒤에 @를 입력하고 타입어헤드에서 세션을 고르면, 서브에이전트를 @-멘션하는 것과 같아요. Claude Code v2.1.232 이상이 필요해요. Claude Code가 @api-worker 같은 멘션을 삽입하고 그 이름이 어느 세션을 가리키는지 Claude에게 말해, Claude가 내 세션을 먼저 나열하지 않고 그 세션에 메시지를 보낼 수 있어요. 이 프롬프트는 멘션으로 대상을 지명해요.

Let @api-worker know the schema migration finished

타입어헤드는 이 머신의 다른 살아있는 세션을 나열해요. 이름의 첫 글자 이상이 필요한 경우는 두 가지예요.

  • 이 머신 너머의 세션: 클라우드·리모트 컨트롤 세션은 Claude가 이 머신 너머의 세션을 나열하거나 메시징한 뒤에만 타입어헤드에 나타나므로, 먼저 Claude에게 나열하라고 하세요.
  • 공백이나 글자·숫자·하이픈·밑줄 외 문자가 있는 이름: @"release notes"처럼 큰따옴표로 입력하세요. 타입어헤드에서 세션을 고르면 Claude Code가 따옴표를 넣어줘요.

피커 없이 멘션을 입력할 수도 있어요. 멘션된 이름에 살아있는 세션이 둘 이상 응답하면 Claude가 보내기 전에 어느 것을 뜻하는지 물어봐요.

Claude가 쓴 메시지가 도착했을 때 어떻게 보이는지(예제 포함)는 메시지는 어떻게 생겼나요를 보세요.

메시지 전달

수신하는 Claude는 활성 턴 중 도구 호출 사이에 메시지를 읽으므로 실행 중인 도구는 절대 중단되지 않아요. 수신 세션이 유휴면 Claude Code가 메시지로 새 턴을 시작해요.

다른 세션의 메시지는 일반 텍스트로 도착해요. 파일이나 MCP 리소스를 @로 언급하면, 메시지가 새 턴을 시작하든 도중에 도착하든 Claude는 언급을 적힌 대로 보고 Claude Code는 아무것도 첨부하지 않아요. Claude는 여전히 수신 머신에서 언급된 경로를 제 도구로 열 수 있고, 그 세션의 권한이 적용돼요. v2.1.251 이전에는 새 턴을 시작한 메시지의 @ 언급이 수신 측에서 파일이나 MCP 리소스를 첨부했어요.

Claude Code는 다음 경우에 메시지를 거부해요.

수신 세션은 도착하는 각 메시지를 자체 인바운드 제어로 확인하고, 검사는 세 가지 결과 중 하나로 끝나요.

  • 전달(Delivered): Claude Code가 메시지를 수신 Claude에게 전달해요.
  • 보류(Held): Claude Code가 메시지를 전달하지 않고 옆에 둬요. 보류된 메시지는 내가 승인하거나 나중에 모드·설정 변경이 허용할 때만 Claude에 닿아요.
  • 거부(Refused): Claude Code가 메시지를 전달하지 않고 버려요.

전달되면 메시지는 내가 입력한 프롬프트처럼 사용량에 세고, 수신 Claude는 단방향 크로스 머신 경우를 제외하고 같은 방식으로 발신자에게 답할 수 있어요.

권한 경계는 세션별로 유지돼요. Claude는 자체 세션에서 거부·차단됐거나 자체 권한 설정이 차단할 행동을 다른 세션에 요청하지 말고, 그 작업을 대신 나에게 다시 라우팅하도록 지시받아요. 수신 측에서는 수신 세션이 들어오는 메시지를 다루는 방식에 따라 메시지가 요청하는 어떤 것에도 그 세션 자체 권한 프롬프트·규칙이 여전히 적용돼요.

다른 세션이 유휴가 될 때 알림 받기

Claude가 이 머신의 세션 중 하나에, 그 세션이 다음에 유휴가 되거나 종료할 때 알림 하나를 다시 보내 달라고 요청할 수 있어요. 여기서 유휴란 세션이 큐에 아무것도 없이 턴을 끝냈다는 뜻이에요. 다른 세션의 긴 작업을 기다리면서 확인하는 대신 끝났을 때 듣고 싶을 때 쓰세요. 두 세션 모두 Claude Code v2.1.236 이상이 필요해요.

알림 요청

무엇을 기다리는지 Claude에게 말하세요. 이 프롬프트는 마이그레이션 세션에서 알림을 요청해요.

Tell me when the migration session finishes what it's working on

Claude는 SendMessage 도구의 notify_when_idle 입력으로 구독해요. 어차피 보내는 메시지에 붙이거나 독립적으로요. 독립적으로는 Claude Code가 지켜보는 세션에서 턴을 시작하거나 토큰을 쓰지 않고 구독하며, 그 세션이 이미 유휴면 즉시 알림을 보내요. 메시지에 붙으면 Claude Code가 먼저 메시지를 전달하고 나중에 알림을 보내요.

각 세션이 보여주는 것

지켜보는 세션은 다른 프로세스가 다음 유휴 때 알려달라고 요청했다는 줄을 보여요. 요청한 세션은 지켜보는 세션을 짚는 줄로 알림을 보여요. 줄은 그 세션의 턴이 끝난 시간과 그 턴의 한 줄 상태를 포함할 수 있어요. 요청한 세션이 유휴면 Claude Code가 알림으로 새 턴을 시작해요.

한계

알림은 일회성이라 Claude Code가 지켜보는 세션에서 한 번 보내고, 어느 세션도 다른 쪽을 폴링하지 않아요. 12시간 안에 알림이 오지 않으면 Claude Code가 구독을 버리고 Claude에게 말해 계속 기다리지 않게 해요.

각 측의 인바운드 제어가 메시지처럼 알림에 적용돼요.

  • 어느 한쪽의 refuse: 아무것도 도착하지 않아요. 지켜보는 세션이 기록·응답 없이 요청을 버려 구독이 12시간 후 무응답으로 만료되고, refuse인 요청 세션은 절대 구독하지 않아요.
  • 어느 한쪽의 hold: 알림이 덜 싣고 도착해요. 지켜보는 세션이 한 줄 상태를 빼고, 요청한 세션은 Claude에 전달하지 않고 트랜스크립트에 알림을 보여요.

주 대화의 Claude만 구독할 수 있고, 이 머신의 내 세션에만 해요. 서브에이전트나 에이전트 팀 팀원이 notify_when_idle을 설정하면 Claude Code가 구독하지 않고 그렇게 말해요. Claude가 다른 에이전트(팀원·서브에이전트·이 머신 너머의 세션)에서 알림을 요청하면 Claude Code가 그에 붙은 메시지를 포함해 전체 호출을 거부하고, Claude에게 거부를 보고해 메시지를 요청 없이 다시 보낼 수 있게 해요.

Claude가 닿을 수 있는 세션 보기

Claude는 메시지 대상을 스스로 찾으므로, 보내라고 하기 전에 아무것도 실행할 필요가 없어요. Claude가 닿을 수 있는 세션을 직접 보려면 /list-agents 명령을 실행하세요. 첫 줄(있을 때)은 이 세션 자신의 이름이고, 내 다른 세션이 그것에 메시지를 보내는 그 이름이에요. 그 아래 행은 Claude가 닿을 수 있는 세션이에요.

  • 서브에이전트: 현재 세션 안에서 도는 에이전트.
  • 팀원: 이 세션 자신의 에이전트 팀 팀원. v2.1.239 이전에는 팀원이 나열에 나타나지 않았지만 Claude는 이미 이름으로 그들에게 메시지를 보낼 수 있었어요.
  • 내 다른 로컬 세션: 같은 머신에서 도는 Claude Code 세션(백그라운드 세션 포함). 세션은 받은 편지함 소켓을 바인딩할 때만 나타나요.
  • 내 클라우드 세션: 웹의 Claude Code 세션. 이 세션이 리모트 컨트롤에 연결되어 있을 때 표시돼요. Claude Code가 나열에서 cloud로 라벨해요.
  • 다른 머신의 리모트 컨트롤 세션: 이 세션이 리모트 컨트롤에 연결되어 있을 때 표시되고 Remote Control로 라벨돼요. 리모트 컨트롤 연결이 끊긴 세션의 상태로 Claude Code가 offline을 보여요.

이 세션은 행 중 하나가 아니에요. Claude가 이 세션 자신의 이름으로 메시지를 주소 지정하면 Claude Code가 거부하고 대상이 현재 세션이라고 Claude에게 말해요. v2.1.239 이전에는 나열이 이 세션의 이름을 보여주지 않았고, Claude Code가 그것에 보낸 메시지를 찾을 수 없는 에이전트로 보고했어요.

이 세션이 리모트 컨트롤에 연결되어 있는 동안 Claude Code는 /list-agents 출력에서 로컬 세션의 일부 세부 정보를 보류하는데, Claude가 메시지를 보낼 세션을 찾을 때 보는 것은 바꾸지 않아요.

  • 작업 디렉터리: 각 로컬 세션의 작업 디렉터리를 빼요.
  • 세션 이름: 사람에게 귀속할 수 없는 세션 이름을 빼서, 이름이 없는 행은 (unnamed session)으로 읽혀요.
  • 첫 줄: 이 터미널에서 --name이나 이름을 붙인 /rename으로 이름을 입력하지 않았다면(세션을 실행하거나 마지막으로 재개한 이후), 이 세션 자신의 이름이 있는 줄을 빼요.

출력이 무엇을 나열하면 세부 정보가 보류됐다는 주석으로 끝나요. 세션 자체 키보드에서 이름 없는 이름으로 /rename`을 실행하면 출력에 나타나는 이름을 그 세션에 줘요.

Claude Code는 클라우드·리모트 컨트롤 세션 목록을 최신순으로 읽고 각각 제한된 페이지 수 뒤에 멈춰요. 내 계정에 그보다 많은 세션이 있으면 Claude Code가 오래된 것을 나열하지 않고, Claude가 이름으로 그들에게 메시지를 보낼 수 없어요. 그러면 Claude Code가 나열에서 그렇게 말하고 Claude도 보낼 때 같은 주석을 봐요.

Claude는 로컬 세션처럼 이름으로 이 머신 너머의 세션을 주소 지정해요. 그 메시지가 어떻게 이동하는지는 다른 머신의 세션에 메시지 보내기를 보세요.

세션은 /rename 명령이나 --name 플래그로 설정한 이름에 응답해요. 설정하지 않으면 Claude Code가 세션에 스스로 이름을 붙여요. 대화형 세션의 경우 그것이 실행 중 세션 목록에 보이는 이름이에요.

세션 이름을 바꾸면 Claude Code가 다른 세션이 그 이름을 조회하는 데 쓰는 공유 레코드도 갱신해요. 그 레코드를 갱신할 수 없으면 /rename 출력에서 다른 세션이 여전히 옛 이름을 보여줄 수 있다고 경고해요. --debug로 세션을 실행하면 Claude Code가 실패한 갱신의 원인을 기록해요.

이 머신의 다른 살아있는 세션이 이미 쓰는 이름으로 세션을 이름 바꾸거나 대화형 하나를 시작·재개하면, Claude Code는 이름을 이미 가진 세션에 남기고 내 것을 변형 이름으로 바꿔요. 세션은 여전히 이름을 공유할 수 있는데, 예를 들어 하나가 더 이른 버전의 Claude Code를 실행하거나 공유 이름이 Claude Code가 생성한 것이면 그래요. 이 세션이 리모트 컨트롤에 연결되지 않았다면 Claude Code가 /list-agents 출력에서 각 로컬 세션의 작업 디렉터리를 보여주므로, 서로 다른 디렉터리에서 도는 같은 이름 세션을 구분할 수 있어요. Claude Code는 이름에 응답하는 살아있는 세션이 몇 개인지에 따라 메시지를 두 가지 방식 중 하나로 주소 지정해요.

  • 이름에 응답하는 세션이 하나: Claude Code가 이름만으로 메시지를 전달해요.
  • 여러 세션이 이름을 공유하거나, 내 세션이 도는 모든 곳을 Claude Code가 확인할 수 없음: Claude가 나열의 각 행에 짧은 식별자를 추가하고 주소에 그 식별자를 써요.

다른 머신의 세션에 메시지 보내기

메시지가 어떻게 이동하고 Anthropic 서버를 통과하는지는 대상 세션이 어디서 도는지에 달려 있어요.

다른 세션이 도는 곳 메시지가 이동하는 방식
이 머신 macOS·Linux에서는 세션당 소켓, 네이티브 Windows에서는 세션당 명명 파이프로. 결코 Anthropic 서버를 통과하지 않음
내 다른 머신 Anthropic 서버를 통해, 그 머신의 리모트 컨트롤 연결로 도착
웹의 Claude Code Anthropic 서버를 통해 클라우드 세션으로 직행

내 다른 머신의 세션과 대화를 시작하려면 Claude Code v2.1.225 이상과 나열에 나타나는 대상이 필요해요. v2.1.225 이전에는 Claude가 그중 하나에서 도착한 메시지에만 답할 수 있었어요.

나열에서 offline으로 보이는 세션(리모트 컨트롤 연결이 끊긴 세션)에 메시지를 보낼 수 있어요. 전송은 성공하지만, 메시지는 그 세션의 머신이 재연결한 뒤에만 도착해요. Claude가 보낼 때 그렇게 들려요.

같은 머신 전달은 기능이 활성화된 곳 어디서든 작동해요. 각 세션은 디스크의 파일에 자신을 등록해요. Claude가 내 로컬 세션을 나열·메시징할 때 Claude Code가 그 파일을 읽어 세션을 찾으므로, 두 세션은 같은 파일을 볼 수 있을 때만 서로 닿을 수 있어요.

컨테이너는 자체 파일시스템을 가지므로 그 안의 세션과 호스트의 세션은 서로 닿을 수 없어요. 같은 컨테이너 안의 두 세션은 셀프 호스팅 러너를 포함해 여전히 메시징할 수 있어요. WSL 2 안의 세션과 같은 컴퓨터의 네이티브 Windows 세션도 서로 닿을 수 없는데, 서로 다른 홈 디렉터리에 등록하고 다른 소켓 유형으로 듣기 때문이에요.

이 세션이 리모트 컨트롤에 연결되어 있는 동안 내 다른 머신의 세션에 메시지를 보내면, Claude Code가 이 세션의 리모트 컨트롤 이름 아래 그 세션의 대화에 메시지를 보여요. 그 머신의 Claude가 그 이름으로 답할 수 있어요. 예를 들어 이 세션이 laptop-graceful-unicorn으로 리모트 컨트롤에 연결되고 내 데스크톱에 메시지를 보내면, 데스크톱 세션에서 laptop-graceful-unicorn 아래 메시지를 봐요.

이 세션이 Claude가 이 머신 너머의 세션에 보낼 때 리모트 컨트롤에 연결되어 있지 않으면 메시지는 여전히 통과하지만 답장 주소 없이 가서 수신 Claude가 답할 수 없어요. Claude가 보낼 때 그렇게 들려요.

어떤 메시지도 이 머신 너머로 가기 전에 내 승인을 요구하려면 isolatePeerMachines을 설정하세요.

세션이 들어오는 메시지를 어떻게 다루나요

세션 A가 세션 B에 메시지를 보내면, Claude Code는 B의 Claude에게 메시지가 내가 아니라 다른 세션에서 왔다고 말하고 메시지가 할 수 있는 것을 제한해요.

  • 아무것도 승인할 수 없음: 다른 세션의 메시지는 절대 내 동의로 세지 않아서, 보류 중인 권한 프롬프트에 내 대신 답할 수 없어요.
  • 구성을 변경할 수 없음: Claude Code는 수신 Claude에게 다른 세션이 요청했기 때문에 권한 설정·CLAUDE.md·기타 구성을 절대 바꾸지 말라고 지시해요.
  • 명령이 실행되지 않음: 메시지 텍스트의 /compact 같은 명령은 일반 텍스트로 도착해요. Claude Code가 절대 실행하지 않아요.
  • 권한 프롬프트는 여전히 발동: 메시지에 따라 행동하는 데 수신 세션이 없는 권한이 필요하면 다른 작업과 같은 프롬프트를 봐요.

메시지는 어떻게 생겼나요

메시지가 도착하면 Claude Code가 어두운 한 줄 미리보기로 대화에 보여주고, 미리보기 줄은 나중에도 대화에 남아요. 미리보기는 발신자 이름과 메시지 첫 줄을 싣고 길면 …으로 자르는데, › Message from @api-worker: Schema migration finished (ctrl+o to expand)처럼요. v2.1.247 이전에는 Claude Code가 미리보기 대신 도착하는 메시지를 전체로 보여줬어요.

다음 중 하나로 전체 텍스트를 볼 수 있어요.

  • Ctrl+O를 눌러 트랜스크립트 뷰어를 열고 발신자 세션 이름 아래 전체 텍스트를 읽어요.
  • --verbose로 시작한 세션에서는 Claude Code가 미리보기 대신 전체 텍스트를 보여줘요.

미리보기는 내가 보는 것만 줄여요. 펼치든 말든 Claude는 전체 메시지를 읽어요.

Claude는 발신자 이름과 답장 주소로 메시지를 받는데, 단방향 크로스 머신 메시지만 답장 주소가 없어요. 이름과 답장 주소 외에 수신 Claude는 메시지 텍스트를 받지, 발신자의 대화 기록이나 파일은 절대 받지 않아요. 메시지 전달이 텍스트의 @ 언급을 다뤄요.

서브에이전트가 쓴 메시지는 메시지 텍스트에 서브에이전트가 식별된 채 발신 세션의 이름 아래 도착해요. 그것에 대한 답은 서브에이전트가 아니라 그 세션의 주 대화에 닿아요.

이 예제는 한 Claude가 다른 Claude에게 쓴 메시지로, 펼쳤을 때 읽히는 전체 텍스트예요.

Schema migration finished
The new column is tenant_id, and rebasing on main is safe now.

인바운드 메시지 제어

crossSessionInbound을 설정해 세션이 내 다른 세션에서 오는 메시지로 무엇을 하는지 고르세요.

값 동작
accept Claude Code가 각 메시지를 Claude에게 전달
hold Claude Code가 각 메시지에 알림을 보여주고 전달하지 않음. 우선순위 규칙에 따라 나중에 accept가 적용되면 Claude Code가 보류된 메시지를 풀어줌
refuse Claude Code가 각 메시지를 전달 없이 버림

설정 파일을 편집하는 것 외에 /config의 Messages from your other sessions 행에서 값을 선택할 수 있어요. Claude Code가 선택한 값을 내 사용자 설정에 써요. 이 행은 Claude Code v2.1.232 이상이 필요하고, 관리 설정이나 --settings 플래그가 키를 설정하는 동안에는 나타나지 않아요. 그때는 사용자 설정 값이 적용되지 않을 테니까요. Claude Code는 이 키에 /config crossSessionInbound=value 약어를 거부해요.

어떤 값이 적용되는지 보려면 설정 참조의 crossSessionInbound 우선순위 규칙을 따르세요. 적용되는 값이 없으면 Claude Code가 두 세션의 권한 모드에서 메시지마다 결정해요. 권한 프롬프트를 우회하는 세션을 한 클래스로 묶고, 다른 모든 세션을 다른 쪽으로 묶어요. Plan 모드는 bypass 권한이 있는 세션에서 우회로 세고, auto·acceptEdits·dontAsk는 프롬프팅으로 세요.

  • 수신 세션이 권한을 프롬프트함: Claude Code가 각 메시지를 전달해요. 발신 세션이 권한 프롬프트를 우회한다고 스스로 식별할 때만 내 승인을 위해 하나를 보류해요.
  • 수신 세션이 권한 프롬프트를 우회함: Claude Code가 각 메시지를 내 승인을 위해 보류해요. 발신 세션이 역시 우회한다고 식별할 때만 하나를 전달해요.

기본이 메시지를 보류하면 Claude Code가 수신 세션에서 승인 대화상자를 열어요. 대화상자는 발신자와 미리보기를 보여줘요.

  • Approve는 그 메시지 하나를 Claude에게 전달해요.
  • Deny나 대화상자 닫기는 버려요.
  • 대화상자가 dialogExpiry 마감을 지나 답 없이 남으면 Claude Code가 닫고 메시지를 버려요. 마감 기본은 5분이에요.
  • 백그라운드 세션에 터미널이 붙어 있지 않으면 Claude Code가 마감을 지나 대화상자를 열어 둬요. 붙은 뒤에도 대화상자가 마감 기간 전체 답 없이 남으면 Claude Code가 닫고 메시지를 버려요.
  • 메시지가 보류 중인 동안 이 세션의 권한 모드 클래스가 바뀌면 Claude Code가 인바운드 규칙을 다시 적용하고, 이제 받아들이는 메시지를 전달하고 알림을 보여요.
  • 메시지가 보류 중인 동안 설정 변경이 refuse를 적용하게 하면 Claude Code가 보류된 메시지를 모두 버리고 닿을 수 있는 각 발신자에게 거부를 보고해요.

발신자가 같은 머신의 대화형 세션이면 수신자가 메시지를 보류할 때 거기에 알림을 보여주고, 수신자가 나중에 전달·거부·만료시키면 후속 알림을 보여줘요. 수신자가 거부하면 여기서 수신자가 크로스 세션 메시지를 받지 않는다는 알림을 보여주고 발신자의 Claude에게 기다리거나 다시 보내지 말라고 말해요.

Claude Code는 전달 큐와 별개로 최대 100개 메시지를 보류하고, 넘으면 가장 오래된 것을 버려요.

비대화형 세션

Claude Code는 대화형처럼 claude -p 세션에 받은 편지함 소켓을 바인딩하므로, 오래 도는 -p 워커가 메시지를 받고 나열에 나타날 수 있어요. bare 모드로 세션을 시작하면 Claude Code가 소켓을 바인딩하지 않아서, 그 세션은 메시지를 받을 수 없고 에이전트 목록에도 나타나지 않아요.

-p 세션은 승인 대화상자를 보여줄 수 없어요. 인바운드 기본이 거기서 메시지를 보류하면 Claude Code가 대화상자가 쓰는 것과 같은 dialogExpiry 마감(기본 5분)동안 유지해요.

  • 마감 전: 모드·설정 변경이 메시지를 허용하면 Claude Code가 전달해요.
  • 마감 후: Claude Code가 메시지를 버리고 닿을 수 있는 발신자에게 만료로 보고해요.

dialogExpiry를 "never"로 설정해 기본 보류된 메시지를 세션이 끝날 때까지 유지하세요. 명시적 hold 설정이 보류한 메시지는 만료되지 않고, 나중에 accept가 적용될 때만 Claude Code가 전달해요.

세션이 여전히 보류된 메시지로 끝나면 Claude Code가 닿을 수 있는 각 발신자에게 만료로 보고해요. v2.1.225 이전에는 -p 세션에 마감이 없어서 보류된 메시지는 실행 중 권한 모드 변경이 전달하지 않는 한 보류로 남았고, 보류 메시지로 끝난 세션은 발신자에게 아무것도 보고하지 않았어요.

-p 워커가 메시지를 무인으로 받게 하려면 --settings 값에서 crossSessionInbound를 accept로 설정해 시작하세요. 사용자 설정의 accept도 작동하지만 내가 실행하는 모든 세션에 적용돼요.

세션의 받은 편지함 소켓

기대한 세션이 에이전트 목록에 없을 때, 스크립트나 훅이 세션에 게시하길 원할 때, 샌드박스된 명령이 소켓에 닿지 못할 때 이 섹션을 읽으세요.

Claude Code는 크로스 세션 메시징이 켜진 각 세션에 받은 편지함 소켓을 바인딩해서, 머신의 다른 세션이 거기 메시지를 전달해요. 소켓은 macOS·Linux(WSL 2 내부 Linux 포함)에서는 유닉스 도메인 소켓, 네이티브 Windows에서는 명명 파이프예요. 어떤 세션 종류가 하나를 바인딩하는지는 비대화형 세션을 보세요.

소켓 경로는 두 곳에서 찾을 수 있어요.

  • /status가 Peer address 행에 보여줘요. 경로 앞에 uds:가 붙어요.
  • Claude Code가 CLAUDE_CODE_MESSAGING_SOCKET 환경 변수로 훅·Bash 명령에 내보내요.
    • 메시징이 켜진 채 시작하는 세션에서 Claude Code는 SessionStart를 포함해 어떤 훅이 실행되기 전에 변수를 내보내요.
    • 각 세션은 부모 세션에서 물려받은 것이 아닌 자체 소켓을 내보내요.

macOS·Linux에서 Claude Code는 소켓을 내 운영체제 사용자로 제한해요. 네이티브 Windows에서는 대신 각 연결이 내 운영체제 사용자만 읽을 수 있는 키로 먼저 인증하기를 요구해요. 어느 쪽이든 공유 머신에서 다른 사용자의 세션은 그것에 전달할 수 없어요.

macOS·Linux에서 Claude Code는 받아들일 수 없는 디렉터리(다른 사용자가 소유한 것 같은)에 소켓을 만드는 것도 거부하고, 대신 비공개 사용자별 디렉터리 /tmp/cc-socks-<uid>를 써요. 어떤 디렉터리도 받아들일 수 없으면 세션은 받은 편지함 없이 돌아요. Claude Code가 알림을 보여주고, /status가 Peer address 행에 unavailable과 이유를 보여주며, --debug 로그가 전체 거부를 기록해요.

소켓 경로와 함께 Claude Code가 세션당 토큰을 CLAUDE_CODE_MESSAGING_TOKEN으로 내보내요. 자체 세션 소켓에 게시하는 스크립트는 연결의 첫 줄로 {"type":"auth","token":"<token>"}을 보낼 수 있는데, <token>은 CLAUDE_CODE_MESSAGING_TOKEN 값이에요. Claude Code가 그 줄을 요구하는지는 플랫폼에 따라 달라요.

  • macOS·Linux(WSL 2 포함): 줄은 선택 사항이에요. Claude Code가 있든 없든 연결을 받아들여요.
  • 네이티브 Windows: 줄이 필요해요. Claude Code가 첫 줄이 유효한 인증 줄이 아닌 연결은 닫고 그 연결에서 아무것도 전달하지 않아요.

게시하는 메시지가 준비됐을 때만 연결을 여세요. Claude Code가 30초 안에 완전한 줄을 보내지 않은 연결을 닫으므로, 느린 명령의 출력을 먼저 캡처한 뒤 연결을 열어 보내세요.

아래 자식 프로세스 메시지 규칙이 Claude Code가 언제 토큰을 상담하고, 검증할 수 없는 메시지를 어떻게 다루는지 말해요.

Claude Code는 소켓에 도착하는 메시지를 다른 피어 메시지와 같은 인바운드 제어로 처리하는데, 예외 하나와 전제 하나가 있어요.

  • 자식 프로세스 메시지: crossSessionInbound 값이 적용되지 않으면, Claude Code는 세션 자체의 자식 프로세스(훅이나 Bash 명령이 자체 세션 소켓에 다시 게시하는 것)에서 왔다고 검증한 메시지를 전달해요.
    • Linux(WSL 2 내부 포함)에서 Claude Code는 이미 종료한 자식에도 프로세스 증거로 검증할 수 있어요. macOS에서는 게시 프로세스가 아직 도는 동안에만 그렇게 검증할 수 있고, Claude Code가 프로세스 ID 1로 도는 컨테이너에서는 프로세스 증거가 전혀 없어요. 네이티브 Windows에서도 없어요.
    • macOS에서 게시 프로세스가 종료된 뒤와 Claude Code가 프로세스 ID 1로 도는 컨테이너에서는 그 프로세스 증거가 없는데, Claude Code가 대신 연결을 연 인증 줄에서 세션이 내보낸 CLAUDE_CODE_MESSAGING_TOKEN을 보낸 자식을 검증해요. 네이티브 Windows에서는 그 토큰이 자식 프로세스 메시지를 검증하는 유일한 방법이에요.
    • Claude Code가 어느 쪽으로도 검증할 수 없으면 그 메시지를 권한 클래스를 주장하지 않는 다른 것처럼 다뤄서, 권한 프롬프트를 우회하는 세션은 내 승인을 위해 보류해요.
  • 샌드박스된 세션: 샌드박스의 유닉스 소켓 설정인 sandbox.network.allowAllUnixSockets와 sandbox.network.allowUnixSockets로 샌드박스 안에서 Bash 명령이 소켓에 닿을 수 있는지 제어해요.

크로스 세션 메시징 제한

메시지별 기본값 말고도 메시징을 두 가지로 좁힐 수 있어요. 어떤 메시지도 머신을 떠나기 전에 내 승인을 요구하거나, 세션이나 조직의 메시징을 끄거나요.

머신 간 메시지 승인 요구

isolatePeerMachines을 true로 설정하면 어떤 SendMessage도 이 머신 너머의 세션에 닿기 전에 내 명시적 승인을 요구해요.

{
  "isolatePeerMachines": true
}

이걸 설정하면, 일반 권한 프롬프트를 건너뛰는 bypassPermissions 모드에서도 Claude Code가 이 머신 너머의 세션으로 가는 Claude의 메시지가 떠나기 전에 내 승인을 물어요. 어느 설정 범위의 true든 적용되므로, 체크인된 프로젝트 파일이 요구 사항을 켤 수는 있지만 끌 수는 없어요. Claude Code는 같은 머신의 세션 사이 메시지에는 프롬프트하지 않아요.

크로스 세션 메시징 끄기

수신과 발신은 별도 제어이므로 필요한 방향(또는 둘 다)을 꺼요. 도착하는 메시지에는 crossSessionInbound를, 여기 Claude가 보내거나 나열하는 것에는 권한 규칙을 쓰세요.

  • 수신 멈춤: crossSessionInbound를 refuse로 설정하면 Claude Code가 인바운드 피어 메시지를 전달 없이 버려요. 프로젝트·로컬 설정에서 refuse는 다른 모든 출처보다 적용되고, 사용자 설정에서는 관리 설정이나 --settings 플래그가 값을 설정하지 않았다면 적용돼요.
  • 발신·나열 멈춤: SendMessage와 ListAgents를 짚는 권한 deny 규칙을 추가하세요. 둘 다 지정자 없는 베어 도구 이름을 받아요.

관리자는 관리 설정에서 두 쪽을 조직에 대해 꺼서 deny 규칙과 refuse를 결합할 수 있어요.

{
  "permissions": {
    "deny": ["SendMessage", "ListAgents"]
  },
  "crossSessionInbound": "refuse"
}

이걸 두면 Claude Code가 여전히 각 세션의 받은 편지함 소켓을 바인딩하지만, 그 위에 도착하는 모든 메시지를 Claude에 아무것도 전달하지 않고 버려요. SendMessage를 거부하면 같은 도구가 둘 다에 쓰이므로 서브에이전트·에이전트 팀 팀원 메시징도 제거돼요. 거부하는 세션은 자체 /status나 같은 머신의 다른 세션 나열에서 보이는 변화가 없으므로, 확인하려면 상태가 아니라 그 세션에 적용되는 설정 파일을 확인하세요.

가용성

크로스 세션 메시징은 macOS·Linux·WSL 2에서 Claude Code v2.1.224 이상, 네이티브 Windows에서 v2.1.234 이상이 필요해요. 가용성과 Claude가 메시징할 수 있는 세션은 운영체제·프로바이더·구성에도 달려 있어요.

  • 운영체제: macOS·Windows·Linux(WSL 2 내부 Linux 포함)에서 사용 가능.
  • 이 머신의 세션: Amazon Bedrock·Claude Platform on AWS·Google Cloud's Agent Platform·Microsoft Foundry를 포함한 모든 프로바이더, 그리고 피처 플래그 fetch를 끈 세션에서 사용 가능. 그 프로바이더들과 플래그 fetch를 끈 상태에서는 같은 머신 메시징에 Claude Code v2.1.248 이상이 필요해요. Claude Code가 이 메시지들을 내 머신의 세션당 소켓으로 전달하지, 결코 Anthropic 서버를 통과하지 않아요. 세션이 그것들을 받지 않게 하려면 crossSessionInbound을 refuse로 설정하세요.
  • 이 머신 너머의 세션: Claude는 리모트 컨트롤에 연결된 세션에서 웹의 Claude Code 세션과 다른 머신의 세션을 찾는데, 이 세션의 활성 인증으로서 claude.ai 로그인과 다른 리모트 컨트롤 요구 사항이 필요해요. Claude는 API 키나 Amazon Bedrock·Claude Platform on AWS·Google Cloud's Agent Platform·Microsoft Foundry에서는 그 세션을 찾을 수 없어요.

세션을 확인하려면 /list-agents(또한 /peers로 사용 가능)를 입력하세요. 결과는 기능이 없는 세션과 더 좁은 무언가(누락된 SendMessage 도구, 거부된 전송 같은)가 메시지를 막은 세션을 구분해요.

메시징이 있는 세션에서 /status도 Peer address 행에 세션 자신의 받은 편지함 주소를 보여주거나, Claude Code가 받은 편지함을 설정할 수 없으면 unavailable과 이유를 보여줘요.

한계

여기 한계는 메시징 채널 자체의 속성이고 기능이 실행되는 곳 어디서든 적용돼요. 플랫폼·프로바이더 간극은 가용성을 보세요.

  • 일반 텍스트만: Claude는 세션 간에 일반 텍스트만 보내요. 구조화된 에이전트 팀 프로토콜 메시지는 팀 내에 머물러요.
  • 같은 머신 메시지 크기 상한: Claude Code가 이 머신의 세션에 보내는 메시지를 직렬화된 형태가 약 100만 문자를 넘으면 거부해요. 거부가 정확한 크기를 짚어요. 수신 세션에 아무것도 닿지 않아요.
  • 한 세션에 대한 급속 버스트는 발신자에서 거부: 이 머신의 세션에 대한 급속 버스트가 그 세션의 받은 편지함이 받는 것에 도달하면 Claude Code가 발신 세션에서 추가 전송을 거부해요. 거부가 버스트를 짚고 나머지를 한 메시지로 배치하거나 기다리라고 Claude에게 말해요. v2.1.236 이전에는 Claude Code가 수신 세션이 그것들을 버리는 동안 그 전송을 보낸 것으로 보고했어요.
  • 메시지 루프가 조절됨: 수신 세션에서 Claude Code가 발신자당 반복 메시지에 속도를 제한하고, 짧은 창 안에 도착하는 동일한 반복을 버리며, Claude가 읽을 메시지를 최대 50개 큐에 넣어요. 따라서 두 세션 사이의 메시지 루프는 스스로 멈춰요. 속도 제한·반복 검사·큐 상한이 이 머신의 대화형 세션 메시지를 버리면 Claude Code가 어느 것이 버렸는지 그 세션에 말하고 그 Claude에게 곧 다시 보내지 말라고 해요.

더 알아보기