Claude Code 2.1.224부터 독립적으로 실행 중인 세션끼리 메시지를 주고받을 수 있다. 한 세션이 ListAgents로 다른 세션을 찾고, SendMessage로 필요한 내용을 전달한다. 같은 팀으로 생성한 teammate만 대화할 수 있었던 기존 방식과 달리, 이미 따로 실행하고 있는 세션을 연결할 수 있다는 점이 핵심이다.

이 기능은 세션을 하나로 합치지 않는다. 각 세션은 자기 컨텍스트와 작업 디렉터리를 그대로 유지하고, 필요한 정보만 메시지로 받는다. 그래서 여러 저장소나 worktree에서 병렬로 작업할 때 사람이 터미널 사이를 오가며 내용을 복사하는 일을 줄일 수 있다.

먼저 버전을 확인한다

cross-session SendMessage는 Claude Code 2.1.224에서 macOS와 Linux에 추가됐다.

1

claude --version

2.1.225부터는 ListAgents에 name [ref] 형식으로 보이는 다른 머신의 Remote Control 세션에도 먼저 메시지를 시작할 수 있다. 여러 머신을 연결해 쓸 계획이라면 2.1.225 이상을 기준으로 잡는 편이 낫다.

별도 명령 문법을 외울 필요는 없다. Claude에게 자연어로 요청하면 Claude가 ListAgents와 SendMessage를 사용한다.

1
2
3
4

현재 접근 가능한 세션을 확인하고 backend-auth 세션에 다음 내용을 보내줘.

POST /sessions 응답에 expires_at 필드가 추가됐어.
OpenAPI 스키마와 클라이언트 타입을 확인해서 영향 범위를 답해달라고 해줘.

세션 이름부터 정리한다

세션이 여러 개면 자동 생성된 제목만으로 대상을 고르기 어렵다. 각 세션에서 /rename으로 역할과 범위를 드러내는 이름을 붙인다.

1
2
3

/rename backend-auth
/rename web-session-client
/rename integration-review

좋은 이름은 기술 이름만 나열하지 않고 소유 범위를 보여준다. backend보다 backend-auth, review보다 checkout-security-review가 낫다. 다른 머신의 Remote Control 세션도 이름으로 찾으므로 중복되지 않는 이름이 중요하다.

메시지를 보내기 전에는 ListAgents로 실제 대상과 상태를 확인하게 한다. 이름이 비슷한 세션을 추측해서 보내지 않는다.

1
2

ListAgents로 web-session-client가 보이는지 먼저 확인해.
정확히 하나만 확인되면 메시지를 보내고, 없거나 둘 이상이면 보내지 말고 알려줘.

메시지는 대화가 아니라 작업 계약으로 쓴다

다른 세션은 현재 세션의 대화 기록을 공유하지 않는다. “아까 말한 방식대로 고쳐줘”처럼 맥락을 생략하면 받는 쪽은 무엇을 뜻하는지 알 수 없다. 메시지 하나만 읽어도 다음 행동을 결정할 수 있어야 한다.

실용적인 메시지는 다섯 부분으로 충분하다.

  1. 무엇이 바뀌었는가
  2. 근거가 어디에 있는가
  3. 받는 세션에 어떤 영향이 있는가
  4. 무엇을 해주길 원하는가
  5. 답장이 필요한가
1
2
3
4
5
6
7

[API 계약 변경]

변경: POST /sessions 응답에 expires_at: string이 추가됨
근거: api/openapi.yaml, server/session.ts
영향: web/session-client.ts의 응답 타입과 만료 표시 로직 확인 필요
요청: 영향 범위를 검토하고 필요한 수정과 테스트를 진행해줘
회신: 수정한 파일, 테스트 결과, 남은 결정 사항을 backend-auth에 보내줘

긴 로그나 전체 diff를 메시지에 붙이지 않는다. 파일 경로, commit, PR, 테스트 결과처럼 받는 세션이 직접 확인할 수 있는 근거를 전달한다. 메시지는 컨텍스트 전체를 복제하는 수단이 아니라 세션 사이의 좁은 인터페이스다.

효과가 큰 사용 패턴

여러 저장소의 계약 변경 전달

백엔드 세션이 API나 이벤트 스키마를 바꾼 뒤 소비자 저장소의 세션에 직접 알린다. 보내는 내용에는 변경된 필드, 호환성, 적용 commit, 필요한 후속 작업을 넣는다. 소비자 세션은 작업 결과와 검증 상태를 다시 보낸다.

이 패턴은 서로 다른 checkout을 유지하면서도 계약 변경을 빠뜨리지 않는 데 유용하다. 단, 메시지를 보냈다고 배포 순서나 호환성 검증이 자동으로 해결되는 것은 아니다. 각 저장소의 테스트와 release gate는 그대로 남겨야 한다.

구현 세션과 리뷰 세션 연결

구현이 끝난 뒤 새 리뷰 세션을 만들고 배경을 다시 설명하는 대신, 이미 실행 중인 리뷰 세션에 commit과 검토 관점을 보낸다.

1
2
3
4
5
6
7

integration-review에 commit abc123을 보내고 다음을 검토해달라고 해줘.

- 기존 클라이언트와 하위 호환되는가
- expires_at이 없는 응답을 안전하게 처리하는가
- timezone 경계 테스트가 충분한가

리뷰 결과는 심각도, 파일 경로, 재현 근거와 함께 답장하게 해줘.

리뷰 결과를 구현 세션으로 직접 돌려보내면 사람은 메시지 운반보다 판단과 승인에 집중할 수 있다.

막힌 작업에 필요한 정보만 전달

한 세션이 다른 세션의 결정이나 결과를 기다릴 때 전체 작업을 넘기지 않는다. 무엇 때문에 막혔는지와 답변 형식을 보낸다.

1
2
3

web-session-client가 timezone 표시 정책 때문에 막혀 있어.
product-contract 세션에 UTC 원문 유지와 사용자 locale 변환 중 어느 쪽이 계약인지 묻고,
결정과 근거 문서 링크만 회신해달라고 해줘.

이렇게 보내면 받는 세션이 문제를 다시 탐색하는 범위를 줄일 수 있다.

조정 세션에서 병렬 작업 상태 모으기

여러 독립 세션을 직접 실행하고 있다면 한 세션을 조정 창구로 사용할 수 있다. 조정 세션은 각 세션에 상태를 묻고 결과를 요약하지만, 작업 자체의 source of truth가 되지는 않는다.

1
2
3

접근 가능한 auth 관련 세션을 확인해.
각 세션에 완료된 결과, 검증, blocker, 다음 행동을 같은 형식으로 요청하고
답변을 표로 정리해줘. 수정이나 배포는 하지 마.

이 패턴에서는 모든 세션에 무차별적으로 메시지를 보내지 않는다. 이름과 프로젝트를 확인하고, 응답 형식을 작게 유지하며, 실제 완료 여부는 commit과 테스트로 검증한다.

Agent Teams와는 목적이 다르다

cross-session messaging은 이미 따로 실행 중인 세션에 메시지를 보낸다. Agent Teams는 리드가 teammate를 생성하고 shared task list로 하나의 팀을 운영하는 별도 기능이다.

  • 독립 세션을 사람이 각각 시작했고 필요한 순간에만 연결하려면 cross-session messaging을 쓴다.
  • 처음부터 리드가 일을 나누고 teammate들이 계속 협업해야 한다면 Agent Teams를 검토한다.
  • 조사 결과만 한 번 돌려받으면 되는 일은 subagent가 더 단순하다.

SendMessage라는 도구 이름이 같아도 대상과 운영 모델이 다를 수 있다. 세션 메시징을 Agent Teams의 팀원 메시징으로 설명하면 안 된다.

권한과 전달 실패를 정상 흐름으로 다룬다

2.1.224에는 crossSessionInbound와 dialogExpiry 설정도 추가됐다. 권한을 우회한 상태로 실행 중인 수신 세션에는 cross-session 메시지가 바로 들어가지 않고 사용자 승인을 기다릴 수 있다. 일반 세션으로 보내는 메시지는 자동 전달되도록 설계됐다.

따라서 메시지를 보냈다는 응답만으로 작업 완료를 가정하지 않는다.

  • 대상 세션이 실제로 발견됐는지 확인한다.
  • SendMessage가 전달 성공을 반환했는지 확인한다.
  • 중요한 요청에는 회신 형식과 기한을 적는다.
  • 회신이 없으면 한 번 상태를 확인하고, 반복 전송으로 inbox를 채우지 않는다.
  • unattended session처럼 사용자가 승인할 수 없는 환경에서는 메시징 제약이 있을 수 있으므로 자동화의 필수 경로로 두지 않는다.

메시지에는 비밀값이나 불필요한 고객 데이터를 넣지 않는다. 다른 세션으로 전달되는 내용도 하나의 권한 경계를 넘는 입력으로 취급한다.

메시지가 아닌 저장소에 남겨야 하는 것

세션 메시지는 일시적인 조정 수단이다. 다음 정보는 commit, 이슈, 설계 문서, 테스트 결과처럼 세션 밖에 남긴다.

  • 최종 API와 데이터 계약
  • 승인된 설계 결정
  • 배포 및 migration 순서
  • 검증 결과와 알려진 제한
  • 다시 시작할 때 필요한 handoff

메시지에는 durable artifact의 위치와 이번에 필요한 행동만 담는다. 그래야 세션이 종료되거나 다른 사람이 작업을 이어받아도 상태를 복구할 수 있다.

바로 적용할 체크리스트

  • Claude Code가 macOS 또는 Linux의 2.1.224 이상인가?
  • 다른 머신의 세션에 먼저 보내려면 2.1.225 이상인가?
  • /rename으로 세션 이름과 소유 범위를 구분했는가?
  • ListAgents로 정확한 대상을 확인했는가?
  • 메시지만 읽어도 변경, 근거, 요청, 회신 조건을 이해할 수 있는가?
  • 결과의 source of truth가 저장소나 이슈에 남아 있는가?
  • 전달 성공과 실제 작업 완료를 구분했는가?

cross-session messaging의 가장 좋은 쓰임은 세션을 자율 조직으로 만드는 것이 아니다. 서로 독립적으로 잘 나눈 작업 사이에서 계약, 발견, 검토 요청을 정확하게 전달하는 것이다. 세션은 독립적으로 유지하고 메시지는 작게 만들수록 이 기능이 효과적이다.

기능 추가와 현재 동작은 Claude Code 공식 v2.1.224 릴리스 노트와 v2.1.225 릴리스 노트를 기준으로 확인했다. 세션 이름과 수명주기는 세션 관리 문서에서 볼 수 있다.