handoff

name	handoff
description	로컬 머신과 원격 머신 사이에서 Claude Code 세션과 작업환경을 통째로 넘기고 되받는다. 사용자가 "/handoff", "/handback", "원격으로 넘겨", "저쪽에서 이어서", "이동해야 하니 넘겨줘", "돌아왔으니 가져와", "회수해줘", "핸드오프 상태", "원격 정리" 라고 말할 때 사용한다. 넘기면 원격이 같은 대화 컨텍스트 그대로 자율 실행한다. 되받을 때는 파일만 회수하고 로컬 세션은 건드리지 않는다.

handoff

이동 직전에 지금 세션과 프로젝트를 원격 머신으로 넘기고, 돌아와서 되받는 도구다.

스크립트가 결정론적 규칙을 소유하고, 이 스킬은 판단이 필요한 부분만 담당한다. 규칙을 스킬이 다시 구현하지 말고 스크립트를 호출해라.

역할 경계

스크립트가 하는 것(재구현 금지):

• 전송 목록 산출, gitignore/포함/제외/시크릿 규칙, 용량 계산
• 리스 판정과 갱신, 스테일 판정, 세션 갈래 감지
• rsync 전송과 백업, 원격 workspace 생성과 정리, 자율 세션 기동
• 보존 기간 판정과 정리 대상 선정

스킬이 하는 것:

• 최초 handoff에서 후보를 사람이 이해할 수 있게 제시하고 선택을 목록 파일에 반영
• 중단·실패 상황을 요약해 다음 조치를 제시
• 원격에서 의존성 설치가 필요한지 판단하고 실행
• Codex 경로의 요약 프롬프트 작성

명령

handoff candidates      # gitignore된 전송 후보를 "<bytes>\t<경로>" 로 출력
handoff include <경로>  # 그 파일을 전송 대상으로 기록
handoff exclude <경로>  # 그 파일을 전송 제외로 기록
handoff "<지시문>"      # 넘기기. 확인 없이 끝까지 진행한다
handback                # 되받기. 미리보기 확인을 받는다
handoff status          # 현재 프로젝트 상태 5항목
handoff clean           # 보존 기간 지난 원격 트리와 백업 정리
handoff bootstrap       # 원격 준비 상태 검사와 미완료분 수행

주요 플래그: --to <host>, --include/--exclude/--secrets <패턴>, --tree-retention/--backup-retention <일>, --size-confirm <바이트>, --free-warn <GiB>, --older-than <일>, --codex, --yes/--no, --force.

/handoff 를 부를 때

1. 사용자의 지시문을 그대로 넘긴다. 지시문이 없으면 대화 맥락에서 "지금 하던 작업을 어떻게 마무리해야 하는가"를 한두 문장으로 만들어 확인 없이 사용한다.
2. handoff "<지시문>" 을 실행한다. 확인을 대신 묻지 마라. 무확인이 이 도구의 요구사항이고, 확인이 필요한 두 경우는 스크립트가 알아서 물어본다.
3. 종료 코드로 상황을 구분해 보고한다.
   • 0: workspace id, herdr --remote <host>, handback 을 안내
   • 3: 사전조건 중단. 이유를 그대로 전하고 조치를 제안(리스가 원격이면 handback, 부트스트랩 미완료면 handoff bootstrap)
   • 4: 전송 실패. 같은 명령을 다시 실행하면 이어진다는 점을 반드시 알려라. 리스는 바뀌지 않았다
   • 5: 파일과 세션은 원격에 있고 리스도 원격이지만 pane 이 안 떴다. handoff 재실행 또는 handback 회수를 안내
4. 최초 handoff 전에 handoff candidates 로 후보를 받아 사용자에게 정리해 보여주고, 각각을 handoff include <경로> / handoff exclude <경로> 로 굳혀라. 이 판단은 스킬의 몫이다. 스크립트는 확인 한 줄만 받고 임의로 거절 목록에 넣지 않는다. 한 번 정하면 다음부터 묻지 않는다.
5. 원격에서 의존성이 필요해 보이면(node_modules 가 제외되었고 package.json 이 있는 등) ssh <host> 'cd <경로> && npm install' 처럼 설치를 한 번 실행한다.

/handback 을 부를 때

1. handback 을 실행한다. 미리보기 확인은 스크립트가 사용자에게 직접 묻는다.
2. 종료 코드 처리:
   • 0: 파일만 회수됐고 로컬 세션은 그대로임을 안내. 원격이 무엇을 했는지 알아야 하면 herdr --remote <host> 로 붙거나 회수된 파일의 변경(git diff)을 보라고 안내
   • 3: 세 갈래다. 각각 다르게 대응해라
     • 원격 상태 판정 불가: 네트워크나 herdr 문제다. 복구 후 재시도. 강제로 우회하지 마라
     • 원격이 작업 중: 사용자가 강제 회수를 원하면 다시 실행하며 승인한다. 정지 후 회수라 안전하다
     • 세션 갈래는 더 이상 존재하지 않는 개념이다. 회수는 로컬 세션을 건드리지 않는다
   • 4: 회수 실패. 재실행이 안전하다
3. 회수 후 원격에 .env 가 사라지고 세션 파일은 남는 것이 정상이다.

실행 중 프로세스

handoff 는 파일과 세션만 넘긴다. 실행 중인 프로세스는 따라가지 않는다. 프로젝트 파일에 쓰고 있는 프로세스가 있으면 스크립트가 exit 3 으로 중단한다. 이 검사는 최선 노력이지 보증이 아니다. 파일을 열고-쓰고-닫는 순간적인 쓰기(tsc --watch 의 재빌드, 셸의 >> 추가)는 구조적으로 놓친다. 통과했다고 "아무도 안 쓴다"고 말하지 마라. 그 결과는 handback 때 원격 내용으로 덮여 사라지기 때문이고, 우회 플래그는 없다.

판정 기준은 cwd 가 아니라 쓰기로 열린 파일 기술자다. 그래서 그 폴더에 cwd 만 걸쳐 있는 셸, 터미널, caffeinate, MCP 서버는 막지 않는다. 너 자신의 셸 도구도 막지 않으므로, 세션 안에서 handoff 를 부르는 것은 정상 동작이다.

중단되면 목록에 나온 pid 와 파일을 사용자에게 그대로 전하고 정리를 제안해라. 프로세스를 임의로 죽이지 마라.

이관 중 차단

handoff 후 넘어간 그 세션에서 프롬프트를 제출하면 UserPromptSubmit 훅이 차단한다. 같은 프로젝트 경로라도 다른 세션은 막지 않으므로, 별개 작업은 새 세션에서 하면 된다. 차단 메시지를 보면 handback 을 제안해라. 훅을 우회하거나 리스 파일을 임의로 고치지 마라.

Codex 경로

--codex 는 파일과 작업환경만 넘기고 원격에서 새 Codex 세션을 시작한다. 대화 히스토리는 따라가지 않는다. 프롬프트는 사용자 지시문 + 아래 네 항목이며 각 항목은 5줄을 넘기지 않는다.

[작업 목표]
[지금까지 한 것]
[다음 할 일]
[주의사항]

파일 내용, 시크릿, 토큰은 요약에 절대 넣지 마라. 요약을 만들 수 없으면 지시문만으로 진행하고 요약이 빠졌다는 사실을 사용자에게 알려라.

하지 말 것

• 확인을 대신 묻거나 스크립트의 무확인 원칙을 우회하지 마라
• 세션 갈래 하드 스톱을 우회하려 하지 마라
• 원격에서 자신이 만들지 않은 workspace, pane, 프로세스를 건드리지 마라
• 원격의 홈 트리와 deny_extra 로 지정된 운영 경로를 건드리지 마라
• 시크릿을 로그나 요약이나 커밋에 남기지 마라