[Claude] Claude Code Cross-session messaging 기능

Claude Code를 터미널 두세 개에 띄워놓고 쓰다 보면, 한 session이 다른 session에 메시지를 보내는 장면을 보게 된다. 2026년 8월 v2.1.224에 들어온 cross-session messaging 기능이다. 이 글은 이 기능이 무엇이고 무엇을 할 수 있고 어떻게 쓰는지 공식 문서 기준으로 정리한다.

1. Cross-session messaging

cross-session messaging은 내 Claude Code session 하나가 내 다른 session에 텍스트 메시지를 전달하는 기능이다. 문서의 정의는 이렇다.

A message is a piece of text one Claude writes to another, never the sender's conversation history or files.

 

핵심은 두 가지다.

 

• 오가는 것은 텍스트뿐이다. 보내는 쪽의 대화 기록이나 파일은 넘어가지 않는다.
• 대상은 내가 직접 띄우고 조종하는 독립 session이다. Claude가 알아서 만든 worker가 아니다.

문서는 활용 예를 둘 든다. session A에서 바꾼 코드가 session B가 기대고 있는 것을 깨뜨릴 때, A가 B에게 먼저 경고한다. B가 막혀 있는 질문에 A가 답을 찾았다면 그 답을 B로 보낸다.

subagent, agent teams와 차이

비슷해 보이는 기능이 세 개라 헷갈리기 쉽다.

 

구분	subagent	agent teams	cross-session messaging
실행 위치	현재 session 안	Claude가 spawn한 여러 session	내가 직접 띄운 독립 session
소통 방식	결과를 호출자에게 return	teammate끼리 메시지 + 공유 task list	텍스트 메시지만
조율 주체	main agent	team이 스스로	사람(내가 양쪽을 조종)
도입 시점	초기부터	v2.1.32 (2026-02, 실험 flag 필요)	v2.1.224 (2026-08, 기본 활성)

 

정리하자면 한 session 안에서 일을 나눠 시키려면 subagent. Claude가 팀을 꾸려 감독하게 하려면 agent teams. 내가 이미 따로 돌리고 있는 session들 사이에 정보를 흘리려면 cross-session messaging을 사용하면 된다.

2. 전달 범위와 경로

메시지가 어떤 경로로 가는지는 상대 session이 어디서 도는지에 따라 다르다.

 

상대 session 위치	전달 경로
같은 머신	session별 Unix socket(macOS/Linux) 또는 named pipe(Windows). Anthropic 서버를 거치지 않는다
내 다른 머신	Anthropic 서버를 거쳐 그 머신의 Remote Control 연결로 도착
Claude Code on the web(구름)	Anthropic 서버를 거쳐 cloud session으로 직행

 

같은 머신이면 별도 설정 없이 바로 된다. 다른 머신이나 cloud session은 현재 session이 Remote Control에 연결돼 있고 claude.ai 로그인이 살아 있어야 한다. 다른 머신 session에 먼저 말을 거는 것은 v2.1.225부터다. 그 전에는 받은 메시지에 답만 할 수 있었다.

 

Remote Control 없이 머신 밖으로 보내면 메시지는 가지만 reply address가 빠진다. 받는 쪽 Claude가 답장할 수 없다는 뜻이다.

 

메시지가 닿지 않는 경우도 있다.

 

• container 안 session과 host session은 filesystem이 달라 서로 못 본다. 같은 container 안의 두 session은 된다.
• WSL 2 session과 native Windows session은 home directory와 socket 종류가 달라 서로 못 본다.
• claude -p로 띄운 headless session은 inbox socket을 열기 때문에 메시지를 받을 수 있다. 단 bare mode로 띄우면 socket을 열지 않아 목록에도 안 뜬다.

3. 사용하는 tool

Claude가 쓰는 tool은 둘이다.

 

ListAgents. 닿을 수 있는 대상을 나열한다. 사용자는 /list-agents(별칭 /peers)로 같은 목록을 볼 수 있다. 첫 줄은 이 session 자신의 이름이고 그 아래로 subagent, teammate, 같은 머신의 다른 local session, cloud session, 다른 머신의 Remote Control session이 종류별로 표시된다. 각 row에는 이름과 [ref], 그리고 busy/idle 상태가 붙는다. Remote Control에 연결되지 않은 상태에서는 local session의 working directory도 같이 보여줘서 이름이 같은 session을 구분할 수 있다.

 

SendMessage. 이름으로 메시지를 보낸다. 입력값은 네 개다.

 

입력	설명
to	받는 session 이름. 이름이 겹칠 때만 [ref]를 덧붙인다
message	본문. 받는 쪽 사람은 첫 줄만 preview로 보므로 첫 줄에 요지를 담아야 한다
notify_when_idle	상대가 idle 상태가 되면 한 번 알려달라는 옵션(6절)
summary	보내는 쪽 transcript에 남는 짧은 label. 전송되지 않는다

session 이름

session은 --name flag나 /rename 명령으로 정한 이름에 응답한다. 이름을 안 정하면 Claude Code가 알아서 붙인다. /rename은 다른 session들이 조회하는 공용 record도 같이 갱신한다. 갱신에 실패하면 다른 session에 옛 이름이 남을 수 있다고 경고한다.

 

v2.1.232부터는 prompt 안에서 @ 뒤에 이름 앞글자를 치면 typeahead로 session을 고를 수 있다. subagent를 @-mention하는 것과 같은 방식이다. 이름에 공백이 있으면 @"release notes"처럼 따옴표로 감싼다. 같은 이름의 살아 있는 session이 둘 이상이면 Claude가 어느 쪽인지 되묻는다.

4. 메시지 수신 session

메시지가 도착하면 받는 session 화면에 흐린 한 줄 preview가 뜬다.

 

› Message from @api-worker: Schema migration finished (ctrl+o to expand)

 

전체 내용은 Ctrl+O로 transcript viewer를 열어 보거나 --verbose로 띄운 session에서는 처음부터 전문이 보인다. v2.1.247 전에는 preview 없이 전문이 바로 표시됐다.

 

받는 쪽 Claude에게 언제 전달되는지가 중요하다.

 

• 받는 session이 작업 중이면 tool call 사이에 읽는다. 실행 중인 tool을 끊지 않는다.
• 받는 session이 idle이면 그 메시지로 새 turn을 시작한다.

Claude에게는 <cross-session-message from="..."> 형태로 감싸져 도착한다. 답장하려면 그 from 값을 to에 넣으면 된다. subagent가 보낸 메시지는 부모 session 이름으로 도착하고 답장도 subagent가 아니라 부모 session의 main 대화로 간다.

메시지는 순수 텍스트다. 본문에 @파일명이 있어도 Claude Code는 아무것도 첨부하지 않는다. /compact 같은 명령이 들어 있어도 실행하지 않고 텍스트로만 취급한다.

5. 설정: 받을지, 막을지, 확인받을지

수신 정책 crossSessionInbound

settings.json의 crossSessionInbound 키로 들어오는 메시지를 어떻게 다룰지 정한다.

 

값	동작
accept	바로 Claude에게 전달
hold	사용자에게 승인 dialog를 띄우고 Approve해야 전달. Deny하거나 닫으면 버림
refuse	받지 않음

 

기본값은 permission mode에 따라 정해진다. 우선순위는 managed settings > --settings flag > project settings > local settings > user settings > 기본값 순이다. /config에서도 바꿀 수 있다.

 

hold 상태의 승인 dialog는 dialogExpiry로 정한 시간(기본 5분) 안에 답이 없으면 닫히고 메시지는 버려진다. "never"로 두면 session이 끝날 때까지 기다린다. 터미널이 붙어 있지 않은 background session은 사람이 attach할 때까지 dialog를 열어둔다.

머신 밖 전송 통제 isolatePeerMachines

isolatePeerMachines: true로 두면 다른 머신이나 cloud로 보낼 때마다 명시적 승인을 요구한다. 어느 scope에서든 true면 하위 scope에서 풀 수 없다.

아예 끄기

permission deny rule에 tool 이름을 넣으면 된다.

 

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

환경 변수

hook과 Bash 명령에는 두 변수가 export된다.

 

• CLAUDE_CODE_MESSAGING_SOCKET: 이 session의 inbox socket 경로. /status에서 uds: 접두어로 표시된다.
• CLAUDE_CODE_MESSAGING_TOKEN: script가 자기 session의 socket에 글을 쓸 때 쓰는 인증 token.

즉 hook script가 자기 session에 메시지를 다시 넣을 수도 있다. Claude Code는 이 경우 process 증거나 token으로 자식 process임을 확인하고 자동 전달한다.

6. idle 알림 notify_when_idle (v2.1.236+)

다른 session에 긴 작업을 맡겨놓고 끝났는지 계속 확인하는 대신, 끝나면 한 번 알려달라고 할 수 있다. 사용자는 이렇게만 말하면 된다.

 

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

 

Claude는 SendMessage의 notify_when_idle 입력으로 구독한다. 메시지 없이 구독만 하면 상대 session에서 turn이 시작되지 않고 token도 쓰지 않는다. 상대가 이미 idle이면 즉시 알림이 온다.

 

• 알림은 one-shot이다. 한 번 오고 끝이며, 어느 쪽도 polling하지 않는다.
• 12시간 안에 알림이 없으면 구독을 버리고 Claude에게 알려서 무한 대기를 막는다.
• main 대화의 Claude만 구독할 수 있다. subagent나 teammate가 시도하면 구독되지 않는다.
• 같은 머신의 session에만 된다.
• 상대가 refuse면 아무것도 안 온다. 어느 한쪽이 hold면 알림은 오되 한 줄 status가 빠지고, transcript에만 남고 Claude에게는 전달되지 않는다.

7. 보안: 메시지는 승인이 아니다

session 사이에 메시지가 오가면 한 session의 권한 제한을 다른 session으로 우회하는 것이 걱정된다. 문서는 이를 "cross-session permission laundering"이라 부르고 여러 겹으로 막는다.

 

받는 쪽 Claude는 이 메시지가 사용자가 아니라 다른 session에서 왔다는 것을 안다. 그리고 메시지는 다음을 할 수 없다.

 

• 승인 대신 못 한다. 다른 session의 메시지는 사용자 동의로 치지 않는다. 대기 중인 permission prompt에 답할 수 없다.
• 설정을 못 바꾼다. 다른 session이 시켰다는 이유로 permission 설정, CLAUDE.md, 기타 config를 바꾸지 말라고 Claude에게 지시한다.
• 명령을 실행 안 한다. /compact 같은 명령은 텍스트로만 도착한다.
• permission prompt는 그대로 뜬다. 메시지 내용을 실행하는 데 권한이 필요하면 받는 session에서 평소처럼 prompt가 뜬다.

 

보내는 쪽에도 규칙이 있다. 자기 session에서 거부됐거나 막힐 것으로 예상되는 작업을 다른 session에 부탁하면 안 된다. auto mode에서는 classifier가 agent 간 메시지를 하나씩 검토하고 다른 agent가 전달한 "승인됐다"는 주장을 신뢰하지 않는 입력으로 취급한다.

8. 제한 사항

• 같은 머신 메시지는 직렬화 기준 약 100만 자를 넘으면 거부된다.
• 짧은 시간에 메시지를 쏟아내 상대 inbox 한도에 닿으면 보내는 쪽에서 추가 전송을 거부한다. 두 session이 서로 답장하는 loop는 이 때문에 알아서 멈춘다.
• cloud와 Remote Control session 목록은 최신순으로 잘라서 보여주므로 오래된 session은 이름으로 못 찾을 수 있다.
• Bedrock, Vertex, Foundry, feature-flag fetching을 끈 환경에서는 같은 머신 messaging에 v2.1.248 이상이 필요하다.

9. 사용 예제

가장 단순한 시나리오다. 한쪽에서 조사를 시키고 결과를 받아온다.

 

터미널 1

claude --name main-dev

 

터미널 2

claude --name researcher

 

main-dev에서 이렇게 말한다.

 

@researcher session에 우리 repo의 OAuth 처리 방식을 조사해 달라고 부탁하고,
끝나면 알려줘.

 

main-dev의 Claude는 ListAgents로 researcher를 확인한 뒤 SendMessage를 부른다. to는 researcher, message는 조사 요청, notify_when_idle은 true다.

 

researcher 쪽 화면에는 이렇게 뜬다.

 

› Message from @main-dev: Investigate how this repo handles OAuth … (ctrl+o to expand)

 

crossSessionInbound가 hold면 여기서 승인 dialog가 먼저 뜬다. 승인하면 researcher의 Claude가 조사를 시작한다.

 

researcher가 turn을 마치면 main-dev에 idle 알림이 한 줄 도착한다. 이제 main-dev에서 결과를 요청하거나 researcher 쪽에서 "결과를 main-dev로 보내줘"라고 하면 반대 방향으로 메시지가 간다. main-dev의 Claude는 그 텍스트를 받아 다음 작업에 쓴다.

 

여기서 기억할 점 하나. researcher가 파일을 고치거나 명령을 실행해야 한다면, 그 permission prompt는 researcher 터미널에 뜬다. main-dev가 무엇을 허용했든 상관없다.

정리

cross-session messaging은 "session 하나가 다른 session을 부하로 부리는" 기능이라기보다, 내가 따로 돌리는 session들 사이에 텍스트를 흘려보내는 통로다. 오가는 것은 텍스트뿐이고 승인 권한은 절대 넘어가지 않으며, 수신 정책은 받는 쪽이 정한다. 긴 작업을 다른 터미널에 맡기고 idle 알림으로 끝을 기다리는 패턴이 가장 실용적이다.

참고

• 공식 문서: https://code.claude.com/docs/en/cross-session-messaging
• agent teams: https://code.claude.com/docs/en/agent-teams
• release notes: v2.1.224(2026-08-07, 첫 도입), v2.1.232(@-mention), v2.1.234(native Windows), v2.1.236(notify_when_idle)