tfx-remote - SKILL.md Agent Skill

name: tfx-remote description: > 원격 관련 표면을 setup/spawn 계열 하나로 통합한 엔트리포인트. setup, spawn, list, attach, send, resume, kill, probe 하위 명령을 기준으로 기존 tfx-remote-setup/tfx-remote-spawn 흐름을 축소 통합한다. argument-hint: "[setup|spawn|list|attach|send|resume|kill|probe] ..."

tfx-remote — remote consolidated entrypoint

tfx-remote는 신규 원격 엔진이 아니라 기존 tfx-remote-setup + tfx-remote-spawn 표면을 한 명령군으로 축소한 통합 진입점이다.

Public subcommands

Subcommand	역할	legacy 매핑
`setup`	hosts 등록/편집/진단/probe-all	`tfx-remote-setup`
`spawn <host> [prompt]`	원격/로컬 세션 생성	`tfx-remote-spawn`
`list`	활성 세션 목록	`tfx-remote-spawn --list`
`attach <session>`	세션 재부착	`tfx-remote-spawn --attach`
`send <session> "<msg>"`	세션에 후속 프롬프트 전송	`tfx-remote-spawn --send`
`resume <session	host	recent>`
`kill <session>`	세션 종료	legacy kill 동작 공식 승격
`probe <host>`	SSH/Tailscale/Claude 연결 체크	`tfx-remote-setup` / `tfx-remote-spawn --probe`

capture / wait는 Phase 4b public consolidation 대상이 아니다. 필요하면 legacy passthrough로만 유지한다.

Dispatch contract

`tfx-remote setup`

기존 tfx-remote-setup 플로우를 그대로 사용한다.

setup
setup --add
setup --edit
setup --probe-all
setup --diagnose

hosts.json 은 user-state 경로 한 곳만 읽고 쓴다.

macOS/Linux: ~/.config/triflux/hosts.json
Windows: %APPDATA%\triflux\hosts.json

기존 references/hosts.json 및 source/packages/global 3곳 fan-out 단계는 더 이상 사용하지 않는다. 첫 실행 시 legacy references/hosts.json 이 발견되면 lazy auto-migration으로 user-state 경로에 자동 이동된다.

`tfx-remote spawn`

기존 tfx-remote-spawn 플로우를 사용하되 아래 preflight를 먼저 수행한다.

user-state hosts.json 존재 확인
호스트명/alias 해석
probe TTL 확인
SSH 실패 시 setup diagnose 또는 setup edit 복귀 경로 제시

preflight 실패 시 중단만 하지 말고 아래 중 하나로 복귀시킨다.

tfx-remote setup --add
tfx-remote setup --edit
tfx-remote setup --diagnose
tfx-remote probe <host>

`tfx-remote resume`

우선순위는 아래와 같다.

세션명이 주어지면 해당 세션 attach/복구
호스트명이 주어지면 해당 호스트의 최근 세션 탐색
recent 또는 생략이면 최근 세션 우선, 없으면 default_host 기준 새 spawn

`tfx-remote kill`

공식 public subcommand다. 세션 종료 전에 psmux/WT 정리 규칙은 .claude/rules/tfx-psmux.md와 AGENTS.md의 detach-first 정책을 따른다.

hosts.json contract

신규 코드는 가능하면 hub/lib/hosts-compat.mjs를 기준으로 해석한다. 저장 위치는 macOS/Linux ~/.config/triflux/hosts.json, Windows %APPDATA%\triflux\hosts.json 이다.

v1 legacy 필드 유지: os, ssh_user, tailscale.ip, tailscale.dns, capabilities
v2 additive 필드 허용: ssh.user, capabilities_v2, last_probe

resolveHost(nameOrAlias) 기준으로 alias, tailscale DNS/IP, ssh_user@host를 canonical host로 정규화한다.

Verification

허용 범위 안에서 Phase 4b가 완료되었는지 확인할 때 최소 검증은 아래와 같다.

node hub/lib/hosts-compat.mjs --self-test
Get-FileHash .claude/rules/tfx-psmux.md, AGENTS.md
legacy alias 문서가 모두 tfx-remote 또는 rule 문서로 위임되는지 확인