tfx-remote-spawn — 원격/로컬 Claude 세션 관리

ARGUMENTS 처리: 이 스킬이 ARGUMENTS: <값>과 함께 호출되면, 해당 값을 사용자 입력으로 취급하여 워크플로우의 첫 단계 입력으로 사용한다. ARGUMENTS가 비어있거나 없으면 기존 절차대로 사용자에게 입력을 요청한다.

psmux 세션 기반으로 Claude를 원격/로컬에서 실행하고 관리합니다. AskUserQuestion 기반 인터랙티브 메뉴로 다중 호출 없이 한번에 처리.

워크플로우

Step 1: 동작 판별

사용자 입력을 아래 순서로 매칭한다. 명확히 매칭되면 바로 실행, 모호하면 AskUserQuestion.

"ultra4에서 보안 리뷰 해"       → spawn(host=ultra4, prompt="보안 리뷰 해")
"세션 목록 보여줘"              → list
"ultra4 세션에 테스트도 해"     → send(session=auto, prompt="테스트도 해")
"아까 그 세션 다시 열어"        → attach(session=most-recent)
"로컬에서 리팩터링 이어서"      → spawn(local, prompt="리팩터링 이어서")

모호한 입력 (예: 인자 없이 호출, 호스트만 명시) → AskUserQuestion:

question: "어떤 작업을 하시겠습니까?"
header: "원격 세션"
options:
  - label: "세션 생성 (Spawn)"
    description: "새 Claude 세션을 원격/로컬에 생성"
  - label: "프롬프트 전송 (Send)"
    description: "기존 세션에 추가 프롬프트 전달"
  - label: "세션 목록 (List)"
    description: "활성 tfx-spawn-* 세션 조회"
  - label: "세션 재부착 (Attach)"
    description: "기존 세션을 WT 탭에 다시 열기"
  - label: "환경 프로브 (Probe)"
    description: "원격 호스트 환경 강제 감지"

Step 2: 호스트 선택

spawn/send/attach/probe에서 호스트가 필요한데 미지정인 경우.

1. references/hosts.json 읽기
2. 등록된 호스트가 1개 → 자동 선택
3. 등록된 호스트가 2개 이상 → AskUserQuestion:

question: "어떤 호스트에서 실행하시겠습니까?"
header: "호스트"
options:
  - label: "ultra4"
    description: "Windows 데스크탑 (SSAFY)"
  - label: "m2"
    description: "MacBook Pro"
  - label: "로컬 (이 머신)"
    description: "현재 머신에서 새 세션 생성"

옵션은 references/hosts.json의 hosts 키에서 동적 생성. hosts.json이 없으면 → /tfx-remote-setup 안내.

Step 3: 세션 선택 (send/attach)

send 또는 attach에서 세션이 미지정인 경우.

node scripts/remote-spawn.mjs --list

활성 세션이 0개 → "활성 세션이 없습니다" 보고 후 종료. 활성 세션이 1개 → 자동 선택. 활성 세션이 2개 이상 → AskUserQuestion:

question: "어떤 세션에 연결하시겠습니까?"
header: "세션"
options:
  - label: "tfx-spawn-ultra4-a1b2c3d4"
    description: "ultra4 | active | 10분 전 생성"
  - label: "tfx-spawn-m2-e5f6g7h8"
    description: "m2 | active | 30분 전 생성"

옵션은 --list 결과에서 동적 생성.

Step 4: 동작별 실행

spawn — 세션 생성

4-1. 핸드오프 생성

프롬프트만 준 경우, 현재 대화 맥락에서 핸드오프를 자동 생성한다.

핸드오프 구조:

## 작업 컨텍스트
- 현재 프로젝트: {프로젝트 경로}
- 작업 중인 파일: {최근 수정 파일 목록}
- 진행 상황: {현재 대화에서 완료한 것}

## 태스크
{사용자 프롬프트 또는 추출된 작업 지시}

## 참고
- {관련 결정 사항이나 제약}

저장: .omc/handoff-{uuid8}.md 사용자가 --handoff <file> 명시 시 자동 생성 건너뜀.

4-2. 환경 확인

node scripts/remote-spawn.mjs --probe {host}

question: "{host}에 Claude Code가 없습니다. 어떻게 하시겠습니까?"
header: "Claude 미설치"
options:
  - label: "설치 안내 보기"
    description: "macOS/Linux: npm install -g @anthropic-ai/claude-code | Windows: winget"
  - label: "다른 CLI로 실행"
    description: "codex 또는 gemini로 원격 작업 실행"
  - label: "다른 호스트 선택"
    description: "호스트 선택 메뉴로 돌아감"
  - label: "취소"
    description: "작업 중단"

4-3. 세션 실행

node scripts/remote-spawn.mjs --host {host} --dir {dir} --prompt {prompt} --handoff {handoff_file}

실행 후 결과 보고:

spawned: tfx-spawn-ultra4-a1b2c3d4
WT 탭에서 Claude@ultra4 세션이 열립니다.

후속 작업 AskUserQuestion:

question: "세션이 생성되었습니다. 추가 작업이 있습니까?"
header: "다음"
options:
  - label: "프롬프트 추가 전송"
    description: "방금 생성한 세션에 추가 지시 전달"
  - label: "다른 호스트에도 spawn"
    description: "다른 머신에 추가 세션 생성"
  - label: "완료"
    description: "작업 종료"

send — 프롬프트 전송

세션이 결정되면:

node scripts/remote-spawn.mjs --send {session_name} --prompt "{prompt}"

전송 후 AskUserQuestion:

question: "프롬프트가 전송되었습니다. 추가 작업이 있습니까?"
header: "다음"
options:
  - label: "추가 프롬프트 전송"
    description: "같은 세션에 다른 프롬프트 전달"
  - label: "다른 세션에 전송"
    description: "세션 선택 메뉴로 돌아감"
  - label: "완료"
    description: "작업 종료"

list — 세션 목록

node scripts/remote-spawn.mjs --list

결과를 테이블로 표시 후, 세션이 있으면 AskUserQuestion:

question: "세션을 선택하여 작업하시겠습니까?"
header: "세션 작업"
options:
  - label: "프롬프트 전송"
    description: "선택한 세션에 프롬프트 전달"
  - label: "재부착"
    description: "선택한 세션을 WT 탭에 열기"
  - label: "완료"
    description: "목록 확인만"

attach — 세션 재부착

node scripts/remote-spawn.mjs --attach {session_name}

probe — 환경 확인

node scripts/remote-spawn.mjs --probe {host}

결과를 정리:

ultra4 환경:
  OS: Windows (win32)
  Shell: pwsh
  Home: C:\Users\SSAFY
  Claude: C:\Users\SSAFY\.local\bin\claude.exe

전제 조건

• psmux 설치 (권장, 전체 기능). 미설치 시 기존 WT+SSH fallback.
• remoteControlAtStartup: true 설정 (triflux setup 자동)
• 원격 호스트: Tailscale 네트워크 + SSH 접속 가능
• 로컬: Windows Terminal
• hosts.json 미설정 시 → /tfx-remote-setup 안내

호스트 설정

references/hosts.json에 호스트 별칭을 등록한다. /tfx-remote-setup으로 인터랙티브 설정 가능.

{
  "hosts": {
    "ultra4": {
      "description": "Windows 데스크탑",
      "aliases": ["울트라", "데스크탑"],
      "default_dir": "~/Desktop/Projects"
    }
  },
  "default_host": "ultra4",
  "triggers": ["원격에서", "다른 머신에서", "다른 컴퓨터에서"]
}