클로드 코드 세션 간 메시징: 업데이트 방법과 실전 사용법

터미널을 여러 개 열어 클로드 코드를 병렬로 쓰다 보면 작은 결정 하나를 옮기는 일이 의외로 번거롭습니다. 프론트엔드 세션에서 API 필드 이름을 확정했는데 백엔드 세션에는 그 대화가 없습니다. 결국 같은 설명을 다시 입력하거나, 앞선 대화를 복사해 붙여 넣게 됩니다.

이번 Claude Code 업데이트에는 이 간격을 줄이는 세션 간 메시지 기능이 들어왔습니다. 독립적으로 실행 중인 세션을 찾고, Claude가 다른 세션에 텍스트 메시지를 직접 보냅니다. 로컬 설치본을 2.1.218에서 2.1.226으로 올린 뒤 frontend-demo와 backend-demo 두 세션을 실행해 검색, 전송, 수신, 회신까지 확인했습니다.

이번 업데이트의 범위

세션 간 메시징의 시작점은 Claude Code 2.1.224입니다. 이후 버전에서 원격 세션 지원과 전달 안정성이 보완됐습니다.

버전	세션 간 메시지 관련 변경
2.1.224	macOS·Linux에서 ListAgents로 세션을 찾고 SendMessage로 메시지를 보내는 기능 추가
2.1.224	우회 권한 모드 세션의 수신 메시지를 승인 대기시키는 crossSessionInbound, 대화 상자 만료 설정 추가
2.1.225	변경 기록에는 다른 컴퓨터의 Remote Control 세션에도 이름으로 먼저 메시지를 시작할 수 있도록 확장했다고 표기. 현재 기능 문서의 회신 전용 안내와 충돌
2.1.225	시작 중이거나 headless 상태인 세션에 메시지가 알림·만료 없이 머무르던 문제 수정
2.1.226	버그 수정과 안정성 개선

이번 확인 시점의 최신 설치 버전은 2.1.226이었습니다. 기능 자체는 2.1.224부터 사용할 수 있지만, 메시지 전달 관련 수정이 이어졌으므로 실제 사용 전 최신 버전으로 맞추는 편이 낫습니다.

업데이트와 버전 확인

기존 설치를 업데이트합니다.

claude update
claude --version

네이티브 설치 경로나 이전 설치 방식 때문에 claude update 뒤에도 예전 버전이 표시되면 최신 버전을 다시 설치합니다.

claude install latest
claude --version

이번 환경에서는 최종적으로 다음 버전을 확인했습니다. 본문의 터미널 이미지는 실제 tmux 실행 출력에서 계정 정보와 불필요한 화면 요소를 제외하고, 글자와 줄 순서를 유지한 채 게시용 터미널 셀로 정리한 캡처입니다.

업데이트 후 인증이 만료됐다는 오류가 나오면 계정 로그인을 갱신합니다.

claude auth login

버전 확인과 로그인까지 끝나면 두 세션을 띄울 준비가 됩니다.

세션 간 메시지의 구조

이 기능은 두 Claude Code 세션의 대화창을 하나로 합치지 않습니다. 세션은 계속 서로 다른 작업 경로와 대화 기록을 유지합니다. 필요한 시점에 한 세션의 Claude가 다른 세션으로 일반 텍스트 메시지를 보내는 구조입니다.

내부에서 사용하는 핵심 도구는 두 가지입니다.

• ListAgents: 현재 연결할 수 있는 다른 Claude Code 세션 탐색
• SendMessage: 특정 세션에 텍스트 메시지 전송

사용자가 이 도구 이름을 직접 호출할 필요는 없습니다. /list-agents 또는 /peers로 세션 목록을 보고, 평소처럼 자연어로 “백엔드 세션에 이 결정을 알려줘”라고 요청하면 Claude가 도구를 선택합니다.

같은 컴퓨터의 macOS·Linux 세션은 로컬 소켓으로 메시지를 주고받습니다. 공식 문서에 따르면 이 로컬 전달은 Anthropic 서버를 거치지 않습니다. 다른 컴퓨터의 세션은 Remote Control 연결을 사용하므로 로컬 전달과 경로가 다릅니다.

세션 간 메시지 사용법

두 세션 준비

기능을 구분하기 쉽도록 서로 다른 폴더에서 두 세션을 실행했습니다. 실제 프로젝트라면 프론트엔드와 백엔드 저장소, 또는 서로 다른 Git Worktree를 사용할 수 있습니다.

첫 번째 터미널은 프론트엔드 역할입니다.

cd frontend
claude --name frontend-demo

두 번째 터미널은 백엔드 역할입니다.

cd backend
claude --name backend-demo

이미 실행한 세션이라면 /rename으로 알아보기 쉬운 이름을 붙일 수 있습니다.

/rename frontend-demo

frontend, backend처럼 너무 짧은 이름보다 프로젝트와 역할을 함께 넣는 편이 좋습니다.

shop-frontend
shop-backend
shop-e2e-tests

이름이 구체적이면 세션이 많아져도 잘못 전달할 가능성이 줄어듭니다.

다른 세션 찾기

프론트엔드 세션에서 다음 명령을 입력합니다.

/list-agents

실제 출력에는 다른 Claude 세션 한 개가 backend-demo라는 이름으로 표시됐습니다.

목록에서는 세션 상태, 이름, 작업 경로, 최근 활동 시점을 확인할 수 있습니다. 상대 세션이 작업 중이면 메시지는 현재 도구 실행이 끝난 뒤 처리됩니다. 대기 상태라면 도착한 메시지가 새 턴을 시작할 수 있습니다.

메시지 보내기

이제 프론트엔드 세션에 전달할 내용을 자연어로 요청합니다.

backend-demo 세션에
“프론트엔드 타입 정의 업데이트를 완료했다”고 알려줘.

이번 실험에서는 이름만 지정했을 때 Claude Code가 대상 확인을 요구하며 backend-demo [7b07fe] 형식을 제안했고, 해당 형식으로 다시 요청하자 전송됐습니다. 이는 이번 2.1.226 로컬 환경에서 관찰한 동작입니다. 공식 문서에서 짧은 참조값의 일반적인 용도는 같은 이름의 세션을 구분하는 것으로 설명합니다.

참조값은 세션 식별용 값입니다. 세션 이름이 겹칠 때는 공식 문서의 예시처럼 name [ref] 형식으로 대상을 구분합니다. 그 밖의 상황에서 확인을 요구하는지는 버전과 실행 환경에 따라 달라질 수 있으므로, Claude Code가 표시한 대상 이름과 작업 경로를 확인한 뒤 화면에서 제안한 형식을 따릅니다.

수신과 회신

백엔드 세션에는 Message from @peer 알림이 나타났습니다. 이어서 Claude가 전달된 내용을 읽고 다음 작업 후보를 정리했습니다.

수신 세션에서 원문을 더 자세히 보고 싶다면 화면 안내대로 Ctrl+O를 사용할 수 있습니다. 회신도 같은 방식입니다.

frontend-demo 세션에
“tenant_id 기준으로 백엔드 검토를 시작할 준비가 됐다”고 회신해줘.

실제로 백엔드에서 보낸 회신은 프론트엔드 세션에 Message from @peer로 도착했습니다. 한쪽 알림만 확인한 것이 아니라 프론트엔드 → 백엔드 → 프론트엔드 왕복까지 동작했습니다.

무엇이 전달되는가

세션 간 메시징을 공유 메모리처럼 생각하면 범위를 과대평가하기 쉽습니다. 넘어가는 것은 Claude가 작성한 텍스트 메시지입니다.

전달되는 것	자동으로 전달되지 않는 것
작업 상태 요약	전체 대화 기록
결정 사항과 제약 조건	프로젝트 파일 자체
오류 원인과 재현 방법	현재 터미널의 환경변수
다음 세션에 필요한 요청	사용자의 권한 승인
파일 경로나 커밋 정보가 담긴 텍스트	동일한 작업 디렉터리와 Git 상태

따라서 “이 파일을 보냈으니 상대가 바로 읽겠지”보다 파일 경로, 기준 브랜치, 확인할 항목을 메시지에 명시해야 합니다. 상대 세션이 다른 저장소나 컴퓨터에 있다면 해당 경로에 접근할 수 있는지도 따로 확인합니다.

실무 활용

API 계약 동기화

프론트엔드와 백엔드를 나눠 작업할 때 필드명, 상태 코드, 요청 형식을 전달합니다.

backend-demo에 다음을 알려줘.
- 응답 필드: tenant_id
- null 허용 안 함
- 프론트 타입 정의 수정 완료
백엔드 응답 스키마 확인을 요청해줘.

단순히 “작업 끝남”이라고 보내는 것보다 결정값과 다음 행동을 함께 넣어야 상대 세션이 바로 이어갈 수 있습니다.

구현과 테스트 분리

구현 세션이 변경한 파일과 테스트 포인트를 테스트 세션에 전달합니다.

e2e-tests 세션에 로그인 흐름 변경 내용을 요약해줘.
수정 파일, 새 리다이렉트 경로, 실패할 가능성이 있는 기존 테스트를 포함해.

테스트 세션은 전체 대화를 다시 읽지 않고도 필요한 배경을 받습니다. 실패하면 재현 명령과 핵심 로그만 구현 세션에 돌려보내는 식으로 왕복할 수 있습니다.

긴 작업의 인계

한 세션이 조사나 빌드를 오래 실행하는 동안 다른 세션은 문서나 리뷰를 맡을 수 있습니다. 완료한 세션이 결과를 요약해 다음 역할에 전달하면 사람이 중간 전달자가 되는 횟수가 줄어듭니다. 여러 터미널의 작업·승인 대기·완료 상태를 한곳에서 확인하려면 Herdr로 여러 AI 코딩 에이전트를 관리하는 방법도 함께 활용할 수 있습니다.

review 세션에 현재 변경의 목적, 주요 diff, 통과한 테스트,
아직 확인하지 못한 위험 요소를 전달해줘.

세션끼리 알아서 협업하기

가능합니다. 공식 문서에 따르면 Claude는 작업 중 다른 세션에 필요한 정보가 생겼다고 판단하면, 사용자가 매번 전송을 지시하지 않아도 SendMessage를 선택할 수 있습니다. 대기 중인 수신 세션에서는 메시지가 새 턴을 시작하고, 작업 중인 세션은 현재 도구 실행을 마친 뒤 메시지를 읽습니다.

처음 세션을 열 때 역할과 연락 조건을 함께 정해두면 흐름이 선명해집니다. 역할마다 받을 입력, 넘길 결과, 멈출 조건을 먼저 적는 방법은 AI에게 작업을 나눠 맡길 때 역할 정의서 쓰는 법에서 더 자세히 볼 수 있습니다. 프론트엔드 세션에는 다음처럼 요청할 수 있습니다.

프론트엔드 구현을 진행해줘.

API 계약 변경, 백엔드 확인이 필요한 사항,
작업을 막는 문제가 생기면 backend-demo 세션에 직접 메시지를 보내줘.
답변이 도착하면 현재 작업에 반영하고 결과를 다시 회신해줘.

백엔드 세션에도 상대 역할과 회신 조건을 지정합니다.

백엔드 구현을 진행해줘.

API 스키마나 응답 필드가 확정되면 frontend-demo 세션에 알려줘.
frontend-demo의 질문이나 변경 요청이 도착하면 검토하고 결과를 회신해줘.

이렇게 준비하면 문제 발견 → 상대 세션에 문의 → 코드·스키마 확인 → 결과 회신 → 현재 작업에 반영하는 왕복을 각 세션이 이어갈 수 있습니다. 사람이 매번 내용을 복사해 옮기지 않아도 되는 것이 핵심입니다.

다만 Cross-session messaging은 사용자가 직접 시작하고 역할을 정한 독립 세션 사이의 연락 수단입니다. 전체 대화나 파일을 공유하지 않고, 상대 세션의 메시지가 사용자 권한 승인을 대신하지도 않습니다. 동일 파일을 함께 수정하면 Git 충돌도 그대로 발생합니다. 반복 메시지에는 속도 제한과 중복 억제가 적용되므로, 무제한 자율 루프로 설계할 기능도 아닙니다.

Claude가 여러 작업자를 직접 만들고 감독하는 구조가 필요하다면 공식 기능인 Agent Teams가 더 맞습니다. 직접 띄운 프론트엔드·백엔드 세션이 필요한 결정과 상태만 주고받게 하려면 Cross-session messaging이 적합합니다.

다른 컴퓨터의 작업 연결

원격 세션 지원은 공식 자료가 서로 맞지 않습니다. 2.1.225 변경 기록에는 SendMessage가 다른 컴퓨터의 Remote Control 세션에도 이름으로 대화를 시작할 수 있게 됐다고 적혀 있습니다. 반면 현재 cross-session messaging 문서는 다른 컴퓨터와 Claude Code 웹 세션에는 회신만 가능하며 먼저 대화를 시작할 수 없다고 안내합니다.

이 글에서 직접 확인한 범위는 같은 Linux 컴퓨터의 로컬 세션 왕복입니다. 원격 흐름은 Remote Control 세션에서 먼저 로컬 세션으로 메시지를 보낸 뒤 회신하는 방식만 공식 문서 기준으로 보는 편이 안전합니다. 원격 선제 전송은 두 공식 자료가 일치하거나 설치 환경에서 별도로 검증되기 전까지 전제로 삼지 않습니다.

Git Worktree와 조합

세션끼리 대화할 수 있어도 같은 폴더를 동시에 수정하면 파일 충돌은 그대로 남습니다. 병렬 구현에는 Git Worktree로 Claude Code·Codex 작업 폴더 분리하기처럼 작업 폴더와 브랜치를 먼저 나누고, 메시징은 결정과 결과를 동기화하는 용도로 쓰는 편이 안전합니다.

worktree A: frontend 기능 구현
worktree B: backend 기능 구현
cross-session message: API 계약과 완료 상태 전달

메시지는 협업 채널이고 Worktree는 파일 격리 수단입니다. 둘의 역할이 다릅니다.

보안과 권한

다른 세션이 보낸 메시지는 사용자의 지시나 승인으로 취급되지 않습니다. 공식 문서가 설명하는 경계는 다음과 같습니다.

• 다른 세션은 권한 요청을 대신 승인할 수 없습니다.
• 설정이나 CLAUDE.md 변경을 메시지만으로 허가할 수 없습니다.
• 메시지 안의 /compact 같은 슬래시 명령은 일반 텍스트입니다.
• 실제 작업에 권한이 필요하면 수신 세션이 사용자에게 다시 요청합니다.
• 우회 권한 모드에서 들어오는 메시지는 crossSessionInbound 설정에 따라 승인 대기할 수 있습니다.

이 제한은 불편함보다 안전장치에 가깝습니다. 악의적이거나 잘못된 세션 메시지가 사용자 승인처럼 작동하면, 여러 세션을 열수록 권한 경계가 약해지기 때문입니다.

메시지에 비밀번호, API 키, 장기 토큰을 넣는 것도 피해야 합니다. 같은 컴퓨터의 로컬 전달이라도 수신 세션의 대화 기록에는 텍스트가 남을 수 있습니다.

보이지 않거나 늦게 도착할 때

버전과 운영체제

먼저 두 세션 모두 버전을 확인합니다.

claude --version

세션 간 SendMessage는 2.1.224에 추가됐습니다. macOS와 Linux에서 사용할 수 있고 WSL 2의 Linux 환경도 포함되지만, 네이티브 Windows는 지원하지 않습니다. 버전이 낮다면 업데이트부터 진행합니다.

공식 문서는 제공자와 설정 조건도 함께 적고 있습니다. Amazon Bedrock, Claude Platform on AWS, Google Cloud Agent Platform, Microsoft Foundry에서는 사용할 수 없습니다. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_TELEMETRY, DO_NOT_TRACK, DISABLE_GROWTHBOOK 중 하나가 설정된 세션에서도 기능이 비활성화될 수 있습니다. 조건을 맞췄는데 목록이 비어 있다면 /list-agents와 /status의 Peer address 항목을 확인합니다.

실행 방식

--bare로 실행한 세션은 수신 소켓을 열지 않으므로 다른 세션 목록에 나타나지 않습니다. 메시지를 받을 세션은 일반 대화형 모드로 실행합니다.

격리된 환경

같은 물리 컴퓨터라도 컨테이너와 호스트처럼 세션 디렉터리와 로컬 소켓을 공유하지 않으면 자동 탐색되지 않을 수 있습니다. 이때는 단순히 폴더 경로만 맞추는 것으로 해결되지 않습니다.

작업 중인 세션

수신 세션이 도구를 실행 중이면 메시지를 즉시 읽지 않고 현재 도구 실행이 끝난 뒤 처리합니다. 전송 성공 표시가 보였다면 잠시 기다린 뒤 상대 세션을 확인합니다.

이름 충돌

동일하거나 비슷한 이름이 있으면 제안된 참조값까지 붙입니다.

backend-demo [7b07fe] 세션에 이 결정 사항을 전달해줘.

프로젝트 이름과 역할을 함께 넣은 세션 이름도 충돌을 줄이는 데 도움이 됩니다.

사용 전 체크리스트

• 두 세션의 Claude Code가 2.1.224 이상인가
• macOS·Linux·WSL 2 환경이며 지원 제공자와 설정을 사용하는가
• 메시지를 받을 세션을 --bare 없이 실행했는가
• /list-agents에서 이름과 작업 경로를 확인했는가
• 이름이 겹치면 name [ref]로 대상을 확정했는가
• 결정값, 기준 브랜치, 다음 행동을 메시지에 포함했는가
• 비밀번호와 토큰을 메시지에 넣지 않았는가
• 파일 충돌 방지가 필요하면 Worktree나 별도 저장소를 사용했는가
• 수신 세션에서 필요한 권한은 사용자가 직접 승인했는가

세션 협업의 변화

클로드 코드의 세션 간 메시지는 여러 에이전트를 자동으로 지휘하는 거대한 오케스트레이터보다 작고 실용적인 기능입니다. 이미 별도 터미널에서 진행하던 작업을 그대로 두고, 필요한 결정과 결과만 직접 넘깁니다.

직접 써보니 가장 큰 차이는 복사·붙여넣기가 줄어드는 데 있습니다. 프론트엔드 세션에서 정한 tenant_id를 백엔드 세션에 전달하고, 백엔드의 준비 상태를 다시 프론트엔드로 돌려받는 흐름이 한 대화 요청으로 이어졌습니다. 다만 파일 격리, 권한 승인, 비밀값 관리까지 대신해 주는 기능은 아닙니다.

세션 이름을 역할 중심으로 정하고, 메시지에 결정값과 다음 행동을 함께 적는 것부터 시작하면 됩니다. 병렬 세션을 자주 쓰는 환경일수록 짧은 상태 공유에 가장 먼저 효과가 나타납니다.

참고 자료

• Claude Code 공식 문서: Cross-session messaging
• Claude Code 공식 변경 기록