Claude Code 세션 간 메시지 교환 및 통신 방법

Claude Code 세션 간 메시지 교환의 의미

두 개의 Claude Code 세션은 동일한 머신에서 동일한 운영체제 사용자로 실행될 때 서로 메시지를 주고받을 수 있습니다. 메시지는 한 Claude가 다른 Claude에게 보내는 단순 텍스트 조각입니다. 메시지에는 대화 기록이나 파일이 포함되지 않습니다. Claude는 ListAgents 도구로 다른 세션을 찾고 SendMessage 도구로 텍스트를 전달하므로, 사용자가 직접 도구를 호출할 필요는 없습니다. 사용자가 상대 세션에 전달할 내용을 말하면 Claude가 직접 메시지를 작성합니다.

이 기능을 세션 간 메시징(cross-session messaging)이라고 합니다. 2026년 8월 기준으로 Claude Code v2.1.224 이상이 필요하며, macOS와 Linux(WSL 2 내의 Linux 포함)에서 실행됩니다. Windows는 기본적으로 지원하지 않으며, Amazon Bedrock, AWS의 Claude Platform, Google Cloud의 Agent Platform, Microsoft Foundry에서는 사용할 수 없습니다. 세션이 이러한 요구 사항을 충족하면 메시징 기능은 이미 활성화되어 있으며 별도의 설정은 필요하지 않습니다. 아래에 설명된 동작은 Anthropic의 세션 간 메시징 문서를 기반으로 합니다.

이 기능은 VPS 환경에서 중요합니다. VPS에서는 세션이 충분히 오래 유지되어 메시지를 주고받을 가치가 있기 때문입니다. 노트북은 덮개를 닫으면 세션이 종료되지만, tmux 환경의 서버에서는 월요일에 시작한 세션이 목요일까지 실행되며 하나의 저장소 컨텍스트를 유지합니다. 이러한 세션이 두 개 이상 존재할 때, 이들이 어떻게 통신하는지는 이론적인 문제를 넘어섭니다. 아직 환경을 구성하지 않았다면 이 가이드에서 전제로 하는 세션 구성을 다루는 tmux 환경에서 Claude Code 실행하기부터 시작하십시오.

두 번째 세션이 토큰 값을 하는 경우

비용부터 고려해야 합니다. 각 세션은 고유한 컨텍스트 윈도우를 가진 별도의 Claude 인스턴스이므로, 동일한 기간 동안 두 세션을 사용하면 비용이 대략 두 배로 발생합니다. 전송된 메시지는 사용자가 입력한 프롬프트와 동일하게 사용량으로 계산됩니다. 조정 작업에는 비용이 따르며, 실제로는 하나의 단계적 순서로 진행되어야 할 작업을 여러 세션으로 나누면 속도가 느려지고 비용이 증가합니다.

두 번째 세션을 사용하는 것이 경제적인 경우는 한 가지 공통점이 있습니다. 두 작업이 서로를 기다리지 않고 동시에 진행되는데, 한 작업에서 얻은 정보를 다른 작업이 중간에 필요로 하는 경우입니다.

• 한 세션이 브레이킹 체인지(breaking change)를 발견하고, 다른 세션은 그로 인해 문제가 발생한 코드를 수정하고 있을 때입니다. Claude가 변경 사항을 요약하여 전달하므로, 사용자가 다른 터미널에 이를 다시 입력할 필요가 없습니다.
• 두 세션이 별도의 git worktree에서 동일한 저장소를 작업하고, 한 세션이 어떤 변경 사항이 반영되었는지 알아야 할 때입니다.
• 긴 마이그레이션이나 테스트 실행 결과가 사용자가 보고 있는 세션으로 보고될 때입니다.
• 빌더 세션과 리뷰어 세션이 있을 때, 리뷰어가 빌더가 생성한 결과물을 읽고 발견한 내용을 다시 전달하는 경우입니다.

작업이 순차적이거나 두 세션이 동일한 파일을 수정해야 하는 경우에는 하나의 세션을 사용하십시오. Claude가 단일 작업 내에서 직접 생성하고 감독하는 조정된 그룹을 원한다면, 이는 별도의 실험적 기능인 에이전트 팀(agent teams)을 사용해야 합니다. 단순히 다른 터미널에서 동일한 대화를 이어가고 싶다면 세션을 재개(resume)하십시오. 세션 간 메시징은 사용자가 직접 시작하고 제어하는 독립적인 세션을 위한 기능입니다.

기능을 활용하기 전에 해당 기능이 존재하는지 확인하십시오

먼저 버전을 확인합니다:

claude --version

해당 숫자를 2.1.224와 비교하십시오. 그런 다음 세션 내부에서 /list-agents를 입력하십시오. 이 명령은 /peers으로도 실행할 수 있습니다. 이 명령은 현재 세션에서 접근할 수 있는 모든 에이전트와 각 에이전트가 응답하는 이름을 출력합니다. 만약 명령 자체가 인식되지 않는다면, 해당 세션은 세션 간 메시징 기능을 지원하지 않는 것이며 설정 파일을 변경해도 이 문제는 해결되지 않습니다. /status을 입력하고 Peer address 행을 찾으십시오. 해당 행에는 uds: 접두사가 붙은 이 세션 고유의 수신함 주소가 포함되어 있습니다.

VPS 사용자에게는 특히 주의해야 할 함정이 하나 있습니다. 세션 간 메시징은 기능 플래그 평가에 의존하는데, 여러 개인정보 보호 변수가 이 평가를 비활성화하여 기능을 기본값인 '꺼짐' 상태로 둡니다. DO_NOT_TRACK, DISABLE_TELEMETRY, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_GROWTHBOOK이 모두 이러한 동작을 수행합니다. 사용자는 서버를 새로 구축할 때 보안을 강화하려고 이 변수들을 ~/.bashrc에 붙여넣은 뒤, 왜 /list-agents가 존재하지 않는지 의아해합니다. 동일한 값이 설정 파일의 env 맵이나 관리형 설정에서 전달될 수도 있으므로, 먼저 셸 환경을 확인하십시오.

env | grep -E 'DO_NOT_TRACK|DISABLE_TELEMETRY|DISABLE_GROWTHBOOK|NONESSENTIAL'

출력되는 변수를 모두 해제하십시오. DISABLE_TELEMETRY 및 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC의 경우, 0이라는 문자열을 포함하여 비어 있지 않은 모든 값이 해당 동작을 활성화하므로, DISABLE_TELEMETRY=0는 의도한 대로 작동하지 않습니다. 기능을 끄려면 변수를 해제하거나 빈 문자열로 설정해야 합니다.

세션에 이름을 지정하십시오. 그렇지 않으면 Claude가 세션을 식별할 수 없습니다

Claude는 세션 이름을 통해 메시지를 전달합니다. 세션을 시작할 때 이름을 설정하십시오:

claude --name builder-api

실행 중인 세션 내부에서 /rename를 사용하여 이름을 설정할 수도 있습니다. 이름을 설정하지 않으면 Claude Code는 작업 디렉터리의 폴더 이름을 기반으로 이름을 생성하며, 예시는 myapp-3f과 같습니다. 이는 세션이 하나일 때는 괜찮지만 네 개가 되면 혼란스러워지며, 두 세션의 이름이 같아질 수도 있습니다. /list-agents 출력은 각 로컬 세션의 작업 디렉터리를 보여주므로 이름이 같은 세션을 구분할 수 있으며, 이름이 충돌할 경우 Claude의 자체 목록에는 주소에 짧은 식별자가 추가됩니다. 직접 이름을 지정하는 것이 식별자를 읽는 것보다 효율적입니다.

재현 가능한 2개 세션 tmux 레이아웃

이 구성은 하나의 저장소에서 빌더 세션과 리뷰어 세션을 동시에 운영하는 방식입니다. 리뷰어는 별도의 git worktree에서 작업하므로 두 세션이 동일한 파일을 수정하는 일은 없습니다. git worktree add에 HEAD를 조합하면 분리된 체크아웃이 생성되며, 이는 커밋보다는 읽기 위주의 세션에 적합합니다.

cd ~/src/api
git worktree add ../api-review HEAD
tmux new-session -d -s agents -n builder -c ~/src/api
tmux new-window -t agents -n reviewer -c ~/src/api-review
tmux send-keys -t agents:builder 'claude --name builder-api' C-m
tmux send-keys -t agents:reviewer 'claude --name reviewer-api' C-m
tmux attach -t agents

Ctrl+b를 입력한 뒤 w를 누르면 윈도우 이름 목록이 표시되어 원하는 윈도우를 선택할 수 있습니다. 빌더 윈도우에서 /list-agents를 실행하십시오. 그러면 작업 디렉터리 ~/src/api-review가 포함된 reviewer-api이 나타나야 합니다. 만약 보이지 않는다면 리뷰어 세션이 시작되지 않았거나 다음 섹션에서 다룰 두 가지 문제 중 하나가 발생한 것입니다. 그런 다음 평이한 언어로 내용을 전달하십시오.

Tell reviewer-api which files I changed for the rate limiter and what to look at first.

Claude가 요약을 작성하여 전송합니다. 사용자가 메시지 본문을 직접 작성할 필요는 없으며, Claude가 보내는 내용은 상황에 따라 달라집니다. 리뷰어 윈도우에서는 대화창에 발신자 이름과 함께 메시지가 나타납니다. 해당 세션이 유휴 상태라면 Claude가 즉시 새로운 턴을 시작합니다. 만약 작업 중이라면 도구 호출 사이의 간격까지 기다렸다가 메시지를 보내므로 실행 중인 명령이 중단되지 않습니다. Claude가 메시지를 읽으면 해당 내용은 한 줄짜리 Message from 행으로 축소되며, Ctrl+O을 눌러 다시 펼칠 수 있습니다. 빌더가 변경 사항을 작게 유지할수록 이 방식은 더 효율적으로 작동합니다. diff가 좁을수록 전달 내용이 간결해지고, 리뷰어 세션이 한 번의 턴으로 검토를 마칠 수 있기 때문입니다. 이는 게으른 시니어 개발자의 기술이 강조하는 습관이기도 합니다.

단일 VPS에서 세션 간 가시성

동일 머신 내에서의 데이터 전달은 Anthropic 서버를 거치지 않습니다. 각 세션은 디스크에 등록 파일을 기록하고 자체 받은 편지함 소켓을 바인딩하며, Claude Code는 해당 파일을 읽어 사용자의 다른 세션을 찾습니다. 이로 인해 서버 환경에서 두 가지 결과가 발생합니다.

소켓은 운영체제 사용자별로 제한됩니다. root 계정으로 시작한 세션과 deploy 계정으로 시작한 세션은 동일한 tmux 서버 내에 나란히 있더라도 서로를 볼 수 없습니다. 한 사용자의 세션은 다른 사용자의 소켓에 접근할 수 없기 때문입니다. 두 세션 모두 동일한 사용자로 실행하십시오.

컨테이너는 고유한 파일 시스템을 가집니다. Docker 내부의 세션과 호스트의 세션은 동일한 등록 파일을 읽지 않으므로 서로 접근할 수 없습니다. 동일한 컨테이너 내부의 두 세션은 정상적으로 메시지를 주고받을 수 있습니다. 일회용 VM에서 코딩 에이전트 실행하기와 같이 격리를 위해 에이전트를 컨테이너에 유지하는 경우, 메시징은 컨테이너 내부에서만 작동하며 컨테이너 경계를 넘어 작동하지 않는다는 점을 유의하십시오.

다른 머신이나 웹에서 실행 중인 세션은 Remote Control이 연결되어 있는 동안에만 목록에 나타나며, 해당 상태로 표시됩니다. 여기서 Claude는 해당 세션 중 하나로부터 도착한 메시지에 대해서만 답장할 수 있습니다. Claude가 먼저 대화를 시작할 수는 없습니다.

메시지가 도착하지 않는 이유

일반적인 원인은 네트워크와 무관합니다. 수신 세션이 메시지 처리 방식을 결정하며, 전달하지 않기로 결정했을 가능성이 높습니다. 모든 수신 메시지는 전달됨, 보류됨(승인 전까지 전달되지 않고 대기), 거부됨(전달 없이 삭제) 중 하나의 결과로 처리됩니다.

적용되는 crossSessionInbound 값이 없을 때, Claude Code는 두 세션의 권한 모드를 비교하여 메시지별로 처리 방식을 결정합니다. 권한 확인 프롬프트를 생략하는 세션과 그렇지 않은 세션을 각각 하나의 그룹으로 분류합니다. auto, acceptEdits, dontAsk는 프롬프트가 발생하는 것으로 간주합니다. Plan 모드는 권한 생략이 가능한 세션에서 생략하는 것으로 간주합니다. 규칙은 다음과 같이 대칭적으로 적용됩니다.

• 권한 확인 프롬프트가 발생하는 수신 세션은 모든 메시지를 전달받습니다. 단, 발신 세션이 프롬프트를 생략하도록 설정된 경우에만 메시지를 보류합니다.
• 프롬프트를 생략하는 수신 세션은 모든 메시지를 사용자의 승인을 위해 보류합니다. 단, 발신 세션 또한 프롬프트를 생략하는 경우에만 메시지를 전달합니다.

따라서 많은 사용자가 처음 구성하는 워크플로우가 의도와 다르게 작동하는 경우가 많습니다. 무인 실행을 위해 --permission-mode bypassPermissions으로 빌더를 시작하고 리뷰어는 기본값으로 두면, 빌더가 보낸 모든 메시지는 아무도 확인하지 않는 승인 대화 상자에서 대기하게 됩니다. 해당 대화 상자는 dialogExpiry 기한이 지나면 닫히며(기본값은 5m), 메시지는 삭제됩니다. 동일한 머신에서 발신 세션은 메시지가 보류될 때 알림을 받으며, 이후 수신자가 메시지를 전달하거나 거부하거나 만료시킬 때 후속 알림을 받습니다. 따라서 소켓을 탓하기 전에 발신자의 화면을 먼저 확인하십시오.

세션이 메시지를 자동으로 처리하게 하려면 crossSessionInbound을 accept로 설정하십시오. 설정 위치에 따라 적용 여부가 결정됩니다. Claude Code는 관리형 설정을 먼저 읽고, 그 다음 --settings 플래그, 마지막으로 사용자 설정을 읽어 가장 먼저 발견된 값을 적용합니다. 프로젝트 또는 로컬 설정의 값은 더 엄격한 경우에만 적용되며, 우선순위는 accept < hold < refuse 순입니다. .claude/settings.json의 accept는 가장 느슨한 설정이므로, 신뢰할 수 있는 소스에서 값이 설정된 경우 무시됩니다. ~/.claude/settings.json에 설정하거나, 특정 세션에 대해 다음과 같이 전달하십시오.

claude --name runner --settings '{"crossSessionInbound":"accept"}'

헤드리스 claude -p 워커는 대화형 세션처럼 수신 소켓을 바인딩하고 목록에 나타나지만, 승인 대화 상자를 표시할 수 없습니다. 보류된 메시지는 이후 모드나 설정이 변경되어 허용될 때까지 보류 상태로 유지됩니다. 위에서 언급한 --settings 라인은 이러한 워커가 메시지를 처리할 수 있도록 허용하는 방법입니다. Bare 모드로 시작된 세션은 소켓을 전혀 바인딩하지 않으므로 메시지를 수신할 수 없으며 목록에도 나타나지 않습니다.

핸드오프가 교착 상태에 빠지는 경우

메시지 루프는 시스템이 자동으로 처리합니다. Claude Code는 발신자별로 반복 메시지에 대한 속도 제한(rate-limit)을 적용하고, 짧은 시간 내에 도착하는 동일한 반복 메시지는 삭제하며, 세션당 읽기 대기 중인 메시지를 50개로 제한하여 두 세션이 영원히 핑퐁(ping-pong)을 주고받지 못하게 합니다. 보류 중인 메시지는 100개로 제한되며, 이를 초과하면 가장 오래된 메시지부터 삭제됩니다.

실제로 발생하는 장애는 루프보다는 핸드오프 과정에서 발생하는 더 조용한 형태의 문제입니다. 세션 A가 작업을 계속하기 위해 세션 B의 답변이 필요한 질문을 던진 뒤 유휴 상태가 됩니다. 이때 B가 메시지를 보류하거나, B가 긴 작업을 수행 중이거나, 혹은 B가 A가 의도하지 않은 질문에 답변하는 경우가 발생합니다. A는 기다립니다. 한 시간 뒤 돌아와 보면 두 세션 모두 유휴 상태이며 작업은 완료되지 않았습니다.

답변이 필요 없는 방식으로 핸드오프를 작성하십시오. 좋은 메시지는 사실이나 결정 사항, 즉 무엇이 변경되었고 결과가 무엇인지를 전달합니다. 나쁜 메시지는 다른 세션에 허락을 구하거나, 발신자가 작업을 진행하지 못하게 막는 답변을 요구합니다. Claude는 이미 자신의 권한 설정으로 차단된 작업을 다른 세션에 요청하지 말고, 대신 사용자에게 해당 작업을 다시 전달하도록 지시받았습니다. 이 규칙을 직접 적용하십시오. 세션이 답변 없이는 진행할 수 없다면, 답변을 제공해야 할 사람은 바로 사용자입니다. 컨텍스트 관리 또한 도움이 됩니다. 흐름을 잃은 세션은 모호한 메시지를 작성하기 때문이며, Claude Code에서의 컨텍스트 관리에서 이 부분을 다룹니다.

수신 메시지를 신뢰할 수 없는 입력으로 처리

Claude Code는 수신하는 Claude에게 해당 메시지가 사용자가 아닌 다른 세션에서 왔음을 알리고, 해당 메시지가 수행할 수 있는 작업을 제한합니다. 다른 세션의 동의는 사용자의 동의가 아니므로, 메시지는 사용자를 대신하여 보류 중인 권한 요청에 응답할 수 없습니다. 또한 다른 세션의 요청이라는 이유만으로 권한 설정, CLAUDE.md 또는 기타 구성을 변경할 수 없습니다. /compact와 같은 텍스트 내부의 슬래시 명령은 일반 텍스트로 전달되며 절대 실행되지 않습니다. 메시지에 따른 작업에 수신 세션이 보유하지 않은 권한이 필요한 경우, 다른 작업과 마찬가지로 동일한 권한 요청 프롬프트가 표시됩니다. 자동 모드에서는 분류기가 전달 전 각 메시지를 검토하며, 차단된 메시지는 수신자에게 도달하지 않습니다. 이러한 제한은 허용적인 모드에서도 유지되므로, 우회하는 세션은 인바운드 메시지를 신뢰하는 대신 기본적으로 보류합니다.

이는 권한에 관한 내용이며 콘텐츠는 포함하지 않습니다. 전송 세션은 풀 리퀘스트 설명, 웹 페이지, 의존성 README 또는 낯선 사람이 작성한 이슈 댓글을 읽었을 수 있으며, 읽은 내용은 다른 세션으로 작성하는 텍스트에 영향을 줄 수 있습니다. 메시지는 데이터입니다. 외부에서 세션으로 들어온 다른 모든 텍스트와 동일한 수준의 의심을 가져야 합니다. 이는 AI 에이전트에서 비밀 유지하기에서 설명하는 원칙과 같습니다. 신뢰 경계를 넘어온 모든 것은 잘못되었을 수 있다고 가정하고, 스스로 권한을 부여하도록 허용해서는 안 됩니다.

이러한 상황을 줄이고 싶다면 두 가지 제어 방법을 사용할 수 있습니다. crossSessionInbound를 refuse으로 설정하면 인바운드 피어 메시지를 전달하지 않고 삭제합니다. 프로젝트 설정이나 로컬 설정에서 이 값을 지정하면 계층 구조상 가장 엄격한 규칙이므로 다른 모든 소스에 우선하여 적용됩니다. 이 세션에서 전송하거나 나열하는 것을 중지하려면 SendMessage 및 ListAgents를 지정하는 권한 거부 규칙을 추가하십시오. 두 규칙 모두 지정자 없이 도구 이름만 작성합니다. isolatePeerMachines을 true로 설정하면 메시지가 이 머신 외부의 세션에 도달하기 전에 사용자의 명시적인 승인이 필요하며, 이 승인은 bypassPermissions 모드에서도 필수입니다.

{
  "crossSessionInbound": "refuse",
  "isolatePeerMachines": true
}

SendMessage을 거부하면 동일한 도구가 두 작업 모두에 사용되므로 하위 에이전트로의 메시징도 제거됩니다. 거부 중인 세션은 자체 /status이나 다른 세션의 목록에 눈에 띄는 변화를 보이지 않으므로, 화면이 아닌 세션 구성을 통해 설정을 확인하십시오.

브리지 및 공유 메모리 MCP 서버

비슷한 시기에 유사한 기능을 수행하는 여러 서드파티 프로젝트가 등장했습니다. 실행 중인 에이전트 간에 텍스트를 중계하는 로컬 에이전트 간 브리지와, 여러 에이전트가 읽고 쓸 수 있는 공유 저장소를 제공하는 MCP(Model Context Protocol) 서버가 그것입니다. 이들을 경쟁자로 보기보다는 다른 형태의 도구로 판단하십시오. 설치 명령어를 실행하기 전에 반드시 해당 프로젝트의 README를 확인해야 합니다. 메시징은 푸시(push) 방식입니다. 발신자가 수신자의 턴에 텍스트를 직접 넣기 때문입니다. 공유 저장소는 풀(pull) 방식입니다. 아무도 방해받지 않으며, 세션이 다음번에 확인할 때 메모를 보게 됩니다. 풀 방식은 천천히 변하는 상태를 관리할 때 더 안정적이며, 세션이 실제로 확인할 때만 작동합니다.

이 방식을 선택한다면 기능 목록보다는 프로세스에 관해 질문해야 합니다. 서버가 어떤 사용자로 실행되는지, 그리고 서버가 시스템에서 무엇을 읽을 수 있는지 확인하십시오. VPS에서 MCP 서버 실행하기에서 해당 설정을 다룹니다. 리포지토리 간 에이전트 기술 공유하기는 세션 간에 실시간 상태가 아닌 지침을 공유하려는 더 간단한 경우를 다루며, 그렇지 않으면 발생했을 많은 메시지 교환을 줄여줍니다. 더 넓은 관점은 VPS에서 코딩 에이전트 실행하기에서 시작하는 것이 좋습니다.

FAQ

Why is /list-agents not recognised in my session?

The session does not have cross-session messaging. Check claude --version against 2.1.224 first, since the feature needs that version or later. Then check the platform, because it runs on macOS and Linux and not on native Windows, and it is unavailable on Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, and Microsoft Foundry. If both are fine, check your shell for DO_NOT_TRACK, DISABLE_TELEMETRY, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, or DISABLE_GROWTHBOOK, because each of those blocks the feature-flag evaluation the feature depends on and leaves it off.

Why did my message to the other session never arrive?

If /list-agents works, messaging is on and something narrower stopped that message. The common cause is permission modes. A session that bypasses permission prompts holds every inbound message for your approval unless the sender also bypasses, and that approval dialog is dropped after the dialogExpiry deadline, five minutes by default. Check the sending session for the held notice. To fix it, set crossSessionInbound to accept in ~/.claude/settings.json or pass it with --settings, because an accept in project or local settings is ignored as the looser value.

Can a Claude Code session in Docker message one on the host?

No. Sessions find each other through registration files on disk and a per-session inbox socket, and a container has its own filesystem, so the two cannot see the same files. Two sessions inside the same container can message each other normally. The same rule explains why a session running as root and a session running as your normal user cannot reach each other: the socket is restricted to the operating system user that owns it.

Is a message from another Claude Code session safe to act on?

Treat the text as untrusted input, because the sending session may have read a web page, a README, or an issue comment written by someone else. Claude Code already stops the message from acting on its own: it cannot approve a pending permission prompt, it cannot change permission settings or CLAUDE.md on request, and a slash command in the text arrives as plain text and never runs. Those protections cover permissions and not judgement, so read what arrived before you tell the receiving session to act on it.

Does cross-session messaging send my code to Anthropic?

Between two sessions on the same machine, no. The message travels over a per-session socket on that machine and never through Anthropic servers, and only the text Claude wrote is sent, never conversation history or files. Messages to a session on another of your machines, or to a session on the web, do travel through Anthropic servers over the Remote Control connection, and in that direction Claude can only reply to a message that arrived, not start one. Set isolatePeerMachines to true to require your approval before anything leaves the machine.