Claude Code 세션 간 메시징 정리

터미널 두 개에 Claude Code를 띄워 놓고 한쪽에서 알아낸 걸 다른 쪽에 복사해 붙이는 일이 생각보다 잦다. 8월 초 v2.1.224에서 이걸 Claude가 대신 해주는 세션 간 메시징(cross-session messaging)이 들어왔다. 두 달쯤 지났으니 공식 문서를 기준으로 한번 정리해 둔다. 2026년 10월 기준이다.

사용 환경의 제약

우선 버전과 OS.

• macOS·Linux(WSL 2 포함): v2.1.224 이상
• 네이티브 Windows: v2.1.234 이상
• Amazon Bedrock·Google Cloud Agent Platform·Microsoft Foundry 같은 서드파티 프로바이더에서 같은 머신 메시징: v2.1.248 이상

조건이 맞으면 따로 켤 것 없이 켜져 있다. 확인은 /list-agents(별칭 /peers)로 한다. 명령이 인식되지 않으면 기능이 없는 세션이다.

같은 머신 안에서는 세션마다 Unix 도메인 소켓(Windows는 named pipe)을 하나씩 열고 그걸로 주고받는다. Anthropic 서버를 거치지 않는다. 다른 머신이나 클라우드 세션으로 보내는 경우는 Anthropic 서버를 거치고, 보내는 세션이 Remote Control에 연결돼 있어야 상대가 목록에 보인다. Remote Control은 claude.ai 로그인이 필요하니 API 키나 서드파티 프로바이더로 쓰는 세션은 머신 밖으로 나가지 못한다.

막히는 경우가 몇 가지 더 있다.

• 컨테이너 안 세션과 호스트 세션은 서로 못 닿는다. 같은 컨테이너 안끼리는 된다
• WSL 2 세션과 네이티브 Windows 세션도 서로 못 닿는다
• --bare 모드로 띄운 세션은 소켓을 열지 않아 받을 수 없다
• 보내는 건 평문 텍스트뿐이다. 대화 기록이나 파일은 따라가지 않는다
• 같은 머신 메시지는 약 100만 자를 넘으면 아예 보내지 않고, 받는 쪽 큐는 50개까지다

왜 만들었나

문서가 드는 장면은 한 세션에서 바꾼 것이 다른 세션의 작업을 깨뜨릴 때 먼저 경고하거나, 한 세션에서 정한 결정을 기다리는 세션에 넘겨주는 것이다. 사람이 하던 “터미널 사이 메신저” 역할을 덜어주려는 기능인 것 같다. 대화 전체를 넘기는 기능은 아니어서, 문서는 맥락을 통째로 옮기고 싶다면 세션 resume을 쓰라고 한다.

다른 세션에서 온 메시지는 사용자 입력으로 취급되지 않는다. 권한 프롬프트를 대신 승인하지 못하고, CLAUDE.md나 권한 설정을 바꾸라는 요청은 따르지 않으며, 메시지 안의 /compact 같은 명령은 그냥 글자로 도착한다. 내 세션에서 거부된 작업을 다른 세션에 시켜 우회하는 것도 하지 않게 되어 있다.

권한 모드가 다르면 기본값이 달라진다. 권한 프롬프트를 띄우는 세션은 메시지를 바로 받고, bypassPermissions 세션은 받은 메시지를 승인 대화상자에 붙잡아 둔다. 대화상자는 기본 5분 뒤 닫히고 메시지는 버려진다. auto 모드는 프롬프트 쪽으로 분류된다.

써 보는 방법

Claude가 ListAgents로 상대를 찾고 SendMessage로 보낸다. 사람이 이 도구를 직접 부를 일은 없고, 시키기만 하면 된다.

다른 터미널에서 돌고 있는 세션한테 마이그레이션 끝났는지 물어봐

받을 세션을 콕 집고 싶으면 @로 멘션한다(v2.1.232 이상). 세션 이름은 /rename이나 --name으로 붙여 두는 편이 편하다. 안 붙이면 Claude Code가 알아서 이름을 짓는데, 나중에 헷갈린다.

@api-worker 한테 스키마 마이그레이션 끝났다고 알려줘

받는 쪽 화면에는 › Message from @api-worker: ... 같은 한 줄 미리보기가 뜨고, Ctrl+O로 펼쳐 본다. 받는 Claude는 미리보기가 아니라 전문을 읽는다. 작업 중이면 도구 호출 사이에 끼워 읽고, 쉬고 있으면 그 메시지로 새 턴을 시작한다.

기다리는 용도로는 notify_when_idle이 제일 쓸모 있어 보인다(v2.1.236 이상, 같은 머신만). “마이그레이션 세션 끝나면 알려줘”라고 하면 상대 세션이 다음에 할 일을 마치고 쉬는 상태(idle)가 되거나 종료될 때 알림이 한 번 온다. 감시당하는 세션은 토큰을 쓰지 않는다. 알림이 12시간 안에 안 오면 구독이 풀린다.

받기 싫은 세션은 crossSessionInbound를 accept·hold·refuse 중 하나로 정한다. /config의 “Messages from your other sessions” 항목에서도 바꿀 수 있다. 머신 밖으로 나가는 메시지마다 내 승인을 받고 싶다면 isolatePeerMachines: true를 둔다.

조금 더 활용해보기

여기부터는 해본 게 아니라, 문서를 읽다가 이렇게 쓰면 되겠다 싶었던 것들이다.

저장소 두 개를 묶어 두기. 이 블로그는 영문 사이트(ondelva)와 이름·시각 토큰을 공유한다. 영문 사이트 세션에서 토큰을 바꾸면 블로그 세션에 “이 토큰 바뀌었으니 확인해”라고 보내게 하면 될 것 같다. 지금은 내가 기억해서 옮기고 있고, 가끔 빠뜨린다.

claude -p 상주 워커. headless(화면 없이 도는) 세션도 소켓을 열기 때문에, 오래 도는 -p 워커를 하나 띄워 두고 다른 세션이 일을 던지는 구성이 된다. 다만 -p는 승인 대화상자를 못 띄우니 --settings로 crossSessionInbound: "accept"를 줘야 무인으로 받는다. 사용자 설정에 accept를 박으면 모든 세션에 적용되니 피하는 게 맞는 것 같다.

hook이 자기 세션에 말 걸기. Claude Code는 hook과 Bash에 CLAUDE_CODE_MESSAGING_SOCKET 환경 변수로 자기 소켓 경로를 넘긴다. 오래 걸리는 빌드나 배포 스크립트가 끝날 때 결과를 이 소켓으로 밀어 넣으면 세션이 그걸 받아 다음 일을 이어간다. 자기 자식 프로세스가 보낸 메시지는 기본으로 통과시킨다. 다만 macOS에서는 보낸 프로세스가 살아 있는 동안만 자식인지 확인되니, 스크립트가 먼저 끝나는 구조라면 CLAUDE_CODE_MESSAGING_TOKEN을 첫 줄 auth로 같이 보내야 한다. 소켓은 30초 안에 한 줄을 다 못 보내면 끊기니 출력을 다 모은 다음 연결해야 한다.

다른 머신에 일 맡기기. 사무실이나 집에 둔 다른 머신에서 Remote Control로 세션을 띄워 두면, 지금 쓰는 머신의 세션에서 그쪽으로 일을 넘길 수 있다(v2.1.225 이상). 상대가 offline이면 다시 연결될 때 도착한다. 다만 이건 Anthropic 서버를 거치니 isolatePeerMachines는 켜 두는 편이 마음 편할 것 같다.

worktree 병렬 작업. 여러 세션이 각자 worktree에서 같은 저장소를 만지고 있다면 머지한 쪽이 나머지에게 “main에 뭐 들어갔다”를 알리게 할 수 있다.

한 가지 걸리는 건, 세션이 늘어날수록 누가 누구한테 뭘 보냈는지 내가 따라가기 어려워진다는 점이다. 루프는 알아서 멈추게 되어 있다지만 세션 네 개가 서로 말 거는 상황은 아직 상상이 잘 안 된다.

일단 블로그 세션과 영문 사이트 세션 둘부터 이름 붙여 연결해 봐야겠다. 써보고 나서 후기는 따로 남기려 한다.