크로스 세션 메시징 — 클로드 코드 세션끼리 메시지를 주고받는 법

크로스 세션 메시징이란 무엇인가

터미널 창을 두 개 이상 띄워 놓고 클로드 코드를 쓰다 보면 반드시 이 순간이 온다. 왼쪽 창에서 데이터베이스 스키마를 하나 바꿨는데, 오른쪽 창은 그 사실을 모른 채 옛 구조로 계속 코드를 짜고 있다. 그러면 왼쪽 결론을 마우스로 긁어 오른쪽에 붙여 넣게 된다. 사람이 두 세션 사이의 배달부가 되는 것이다.

크로스 세션 메시징은 그 배달을 세션끼리 직접 하게 하는 기능이다. 한 세션의 클로드가 다른 세션의 클로드에게 글 한 덩이를 보낸다. 공식 문서의 표현대로 '메시지는 한 클로드가 다른 클로드에게 쓰는 텍스트'이고, 대화 기록이나 파일이 아니다.

언제 쓰냐면 대개 셋 중 하나다. 첫째, 한쪽에서 남을 깨뜨리는 변경이나 결정이 나왔을 때 그 사실을 영향받는 세션에 넘긴다. 둘째, 같은 저장소를 여러 워크트리에서 나눠 작업할 때 무엇이 반영됐는지 서로 알린다. 셋째, 오래 걸리는 작업(마이그레이션·테스트)의 상태를 지켜보는 세션 쪽으로 보고하게 한다.

요건은 버전과 운영체제뿐이다. 별도 설치도, 설정 파일에 켜는 스위치도 없다. 요건을 만족하는 세션이면 이미 켜져 있다.

claude --version

# 2.1.224 미만이면 업데이트
claude update

세션 이름이 곧 주소다 — /peers

이 기능을 쓰면서 가장 먼저 찾게 되는 것이 '그럼 상대 주소를 어떻게 쓰나'이다. 답은 주소가 따로 없다는 것이다. 세션 이름이 곧 주소다. IP도 포트도 토큰도 손으로 다룰 일이 없다.

확인하려면 프롬프트에 /peers를 친다. /list-agents라고 쳐도 같다. 첫 줄에 지금 이 세션의 이름이 나오는데, 이것이 다른 세션들이 나를 부를 때 쓰는 이름이다. 그 아래로 내가 닿을 수 있는 상대가 죽 나열된다. 이 세션 안에서 돌고 있는 서브에이전트, 이 세션의 팀 동료, 같은 컴퓨터의 다른 클로드 코드 세션, 그리고 원격 제어에 연결돼 있다면 클라우드 세션과 다른 컴퓨터의 세션까지.

같은 컴퓨터의 세션은 이름 옆에 작업 폴더가 함께 나온다. 이름이 비슷비슷한 세션이 여럿일 때 어느 것이 어느 프로젝트인지 이 폴더로 가른다.

이름을 내가 정하고 싶으면 두 가지 방법이 있다. 시작할 때 claude -n 조사처럼 붙이거나, 이미 켜 놓은 대화에서 /rename 조사라고 친다. 이름을 안 붙이면 클로드 코드가 작업 폴더 이름을 바탕으로 알아서 하나 만들어 준다. 같은 이름을 쓰는 세션이 이미 살아 있으면 뒤에 온 쪽에 변형된 이름이 붙고 그 사실을 알려 준다.

여기서 한 가지 유의할 점. 목록에 이 세션 자신은 행으로 나오지 않는다. 클로드가 실수로 자기 이름으로 보내면 '그건 지금 이 세션'이라고 거절당한다.

# 시작할 때
claude -n 조사

# 이미 켜 놓은 대화에서
/rename 조사

# 닿을 수 있는 상대 확인 (=/list-agents)
/peers

보내는 법 — 도구를 부르지 않고 말로 시킨다

메시지를 보내는 도구는 SendMessage, 상대를 찾는 도구는 ListAgents다. 그런데 이 이름들을 외울 필요는 없다. 사람이 그 도구를 직접 부르는 일은 없기 때문이다. 그냥 무엇을 알리고 싶은지 말하면 클로드가 상대를 찾고 문장을 써서 보낸다.

문구까지 내가 정해 줄 필요도 없다. '방금 우리가 한 걸 결제 API 작업하는 세션한테 설명해 줘'라고만 해도 클로드가 요약을 직접 써서 보낸다. 그래서 같은 지시를 두 번 해도 나가는 문장은 매번 조금씩 다르다.

상대를 콕 집고 싶으면 프롬프트에서 @를 치고 이름의 앞 글자 몇 개를 넣는다. 살아 있는 세션이 자동완성으로 뜨고, 고르면 @api-worker 같은 멘션이 삽입된다. 이러면 클로드가 목록을 뒤지지 않고 곧장 그 세션에 보낸다. 이 자동완성은 2.1.232부터다.

클로드가 스스로 판단해서 보내기도 한다. 내가 시키지 않아도 방금 한 변경이 다른 세션의 작업을 깨뜨린다고 보이면 그쪽에 먼저 알린다.

다른 터미널에서 돌던 마이그레이션 끝났는지 물어봐 줘

방금 우리가 한 걸 결제 API 작업하는 세션한테 설명해 줘

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

받는 쪽에서 벌어지는 일과 유휴 알림

받는 세션이 한창 일하는 중이면 어떻게 될까. 돌던 도구를 끊지 않는다. 받는 쪽 클로드는 도구 호출과 호출 사이에 메시지를 읽는다. 그 세션이 놀고 있으면 클로드 코드가 그 메시지로 새 턴을 시작한다. 어느 쪽이든 화면에는 보낸 세션의 이름과 함께 메시지가 그대로 남는다.

이 기능에서 실제로 가장 자주 쓰게 되는 것은 메시지가 아니라 유휴 알림이다. '마이그레이션 세션 끝나면 알려줘'라고 하면 클로드가 SendMessage의 notify_when_idle 옵션으로 구독을 건다. 그 세션이 다음에 한가해지거나 종료될 때 알림이 딱 한 번 온다. 여기서 한가해졌다는 것은 큐에 아무것도 없는 채로 턴을 마쳤다는 뜻이다.

구독의 장점은 값이 싸다는 데 있다. 메시지 없이 구독만 걸면 지켜보는 쪽 세션에서는 턴이 시작되지도 않고 토큰도 쓰이지 않는다. 이미 한가한 상태면 알림이 즉시 온다. 양쪽 다 상대를 반복해서 찔러 보지 않는다는 점이 중요하다 — 폴링을 대체하려고 만든 기능이다.

제약이 셋 있다. 한 번만 온다. 같은 컴퓨터의 세션에만 걸 수 있다. 그리고 메인 대화의 클로드만 걸 수 있어서 서브에이전트나 팀 동료가 시도하면 구독되지 않는다고 알려 준다. 12시간 안에 아무 신호가 없으면 구독은 만료되고 클로드에게 그렇게 알린다.

무엇이 넘어가고 무엇이 안 넘어가나

이 기능을 안전하게 쓰려면 경계를 한 번 정확히 봐 두는 편이 낫다. 넘어가는 것은 평문 텍스트뿐이다. 파일도, 그동안 쌓인 대화 기록도, 권한도 따라가지 않는다. 받는 세션은 보낸 쪽이 무엇을 읽었고 무엇을 실행했는지 알지 못한 채 그 문장만 받는다.

그래서 맥락을 통째로 옮기고 싶은 경우라면 이 기능이 아니다. 그건 세션 재개(claude --resume)가 할 일이다. 메시지는 '지금 이 사실을 저쪽이 알아야 한다'일 때 쓴다.

권한도 세션마다 따로 논다. 여기서 거부당한 작업을 옆 세션에 시켜 우회하는 것은 규칙으로 금지돼 있다. 그리고 실제 강제는 받는 쪽에 걸려 있다 — 남의 세션에서 온 메시지는 승인이 될 수 없고, CLAUDE.md나 권한 설정을 바꾸라는 요구도 따르지 않게 지시돼 있으며, 본문에 /compact 같은 슬래시 명령을 적어 보내도 그냥 글자로 도착할 뿐 실행되지 않는다. 메시지가 시킨 일에 권한이 필요하면 평소와 똑같은 승인 창이 뜬다.

전달 경로도 어디로 가느냐에 따라 갈린다. 같은 컴퓨터 안이면 세션마다 하나씩 붙는 유닉스 소켓(윈도우는 명명된 파이프)으로 직접 가고 서버를 거치지 않는다. 반대로 다른 컴퓨터나 웹의 세션으로 보내면 Anthropic 서버를 지난다. 아예 밖으로 나가는 것을 막고 싶으면 isolatePeerMachines를 켜서 매번 승인을 받게 할 수 있다.

기본값은 승인 대기가 아니다 — 그리고 안 보일 때

'남의 세션이 내 세션에 말을 걸 수 있다'는 말에 먼저 걱정이 앞선다면, 실제 규칙을 보고 나면 정리가 된다. crossSessionInbound 설정으로 받는 쪽 동작을 셋 중에 고른다. accept는 그대로 전달, hold는 알림만 띄우고 전달하지 않음, refuse는 조용히 버림이다. 설정 파일 대신 /config의 '다른 세션에서 온 메시지' 행에서 골라도 된다.

아무 값도 설정하지 않았을 때가 흔한 오해의 지점이다. 이때 기본은 '무조건 승인 대기'가 아니다. 두 세션의 권한 모드를 비교해서 정한다. 받는 세션이 평소처럼 권한을 물어보는 모드라면 메시지는 그냥 전달되고, 보내는 쪽이 권한 확인을 건너뛰는 모드일 때만 승인을 받는다. 반대로 받는 세션 자체가 권한 확인을 건너뛰는 모드라면 기본이 보류이고, 보내는 쪽도 같은 모드일 때만 전달된다.

승인 창이 떴는데 내가 답을 안 하면 dialogExpiry 기한이 지날 때 창이 닫히고 메시지는 버려진다. 이 기한의 기본값이 5분이다. never로 두면 세션이 끝날 때까지 기다린다. 참고로 명시적으로 hold로 설정해서 보류된 메시지는 만료되지 않고, 나중에 accept가 적용될 때 배달된다.

마지막으로 안 보일 때의 점검 순서. /peers 자체가 인식되지 않으면 이 기능이 없는 것이므로 claude --version부터 본다. /peers는 되는데 보낸 것이 도착하지 않았다면 더 좁은 이유다. SendMessage·ListAgents에 거부 규칙이 걸려 있거나, 받는 쪽 설정이 보류·거부이거나, 상대가 컨테이너 안처럼 파일 시스템이 다른 곳에 있는 경우다. 컨테이너 안 세션과 호스트 세션은 서로 못 본다. WSL 2 안의 세션과 같은 컴퓨터의 네이티브 윈도우 세션도 마찬가지다.

# 1) 기능 자체가 있는가
claude --version        # 맥·리눅스 2.1.224+ / 윈도우 2.1.234+
/peers                  # 인식이 안 되면 기능 없음

# 2) 내 소켓 주소가 잡혀 있는가
/status                 # Peer address 행 확인

# 3) 받는 쪽이 막고 있지 않은가 (~/.claude/settings.json)
{ "crossSessionInbound": "accept" }