tfx-wt

tfx-wt — Windows Terminal 자연어 조작

ARGUMENTS 처리: 이 스킬이 ARGUMENTS: <값>과 함께 호출되면, 해당 값을 사용자 입력으로 취급한다. ARGUMENTS가 비어있거나 없으면 사용자에게 의도 확인 후 적절한 action 으로 라우팅한다.

인프라: keyword-rules.json 의 wt-tab-* 4 규칙이 이 스킬로 라우팅한다. 사용자는 보통 자연어로 호출 ("탭 열어줘") 하므로 의도 → action 매핑이 첫 단계.

OS 정책

이 스킬은 Windows 전용. macOS/Linux 의 탭/패인 자연어 라우팅은 본 스킬 범위 외다.

OS	동작	라우팅
Windows	wt.exe 실제 호출 (wt-manager 경유). safety-guard 차단 우회	tfx-wt 가 담당
macOS / Linux	createWtManager() 가 stub 반환 (PR #241). 모든 action no-op	terminal-opener.mjs 가 tmux 경로로 담당 (PR #236). tfx-wt 는 사용자에게 안내만

분리 정신 (PR #236, #241)

레이어	역할
hub/team/wt-manager.mjs	Windows-only (non-Windows 에서 stub). tfx-wt 가 사용
hub/team/terminal-opener.mjs	Cross-platform abstraction. Windows→wt-manager, macOS/Linux→tmux
hub/team/runtime-strategy.mjs	psmux (Windows) 와 tmux (macOS/Linux) runtime identity 분리 유지

macOS 사용자가 "탭 열어"라고 했는데 본 스킬로 들어오면 잘못된 라우팅. 사용자에게 다음을 안내한 뒤 종료:

• "Windows Terminal 은 macOS 에 없습니다."
• "macOS 에서 새 탭/패인 자동 생성이 필요하면 terminal-opener.mjs 의 tmux 경로를 사용하세요."
• "오케스트레이션 (swarm worker 배치, dashboard) 은 자동으로 OS 분기됩니다."

wt-manager.mjs 자체가 OS-aware 이므로 스킬 코드에서 platform 분기 불필요.

의도 → action 매핑

자연어 입력	action	예시
새 탭, tab open, 탭 추가/생성/열어/띄워, 터미널 탭	create-tab	"새 탭 열어줘"
패인 분할, pane split, 화면 나눠	split-pane	"패인 가로로 분할"
탭 + 여러 개 동시 배치, layout, dashboard	layout	"워커 3개 가로로 배치"
탭 목록, 탭 리스트, 열린 탭, 현재 탭	list	"지금 탭 뭐있어"
탭 닫아, 탭 종료, tab close, 탭 정리	close	"worker 탭 닫아"
오래된 탭 정리, stale 탭, idle 탭 정리	close-stale	"1시간 넘은 탭 정리해"
탭 이름 변경, 탭 제목 바꿔, rename	rename	"이 탭 이름 backend 로 바꿔"

wt + psmux 통합 패턴 (Windows 기본 사용 흐름)

triflux 의 WT triflux 프로파일은 commandline = psmux (wt-manager:319 의 ensureWtProfile). 즉 wt 의 새 탭/패인 = wt 가 컨테이너, 그 안에서 psmux 가 멀티플렉서로 도는 구조. swarm worker, dashboard, 장기 세션 모두 이 형태.

레이어	역할
wt	윈도우 / 탭 / 패인 컨테이너
psmux (탭 내부 default 셸)	세션 호스팅. detach → wt 닫혀도 살아있음 → 재첨부 가능

전형적인 wt sp 한 줄 (.claude/rules/tfx-psmux.md RULE 5-3 인용):

wt.exe -w 0 sp -H -p triflux --title "worker" psmux attach-session -t SESSION

이걸 본 스킬에서 호출하려면 split-pane 또는 create-tab 의 command 에 psmux attach-session -t <session> 을 넣는다. 다중 worker 동시 배치는 layout.

Swarm worker 다중 배치 (전형)

node scripts/wt-cli.mjs layout '[
  {"title":"w1","command":"psmux attach-session -t s1","direction":"H"},
  {"title":"w2","command":"psmux attach-session -t s2","direction":"V"},
  {"title":"w3","command":"psmux attach-session -t s3","direction":"V"}
]'

각 패인이 미리 띄워둔 psmux session (s1/s2/s3) 에 attach. wt 패인 닫혀도 psmux session 은 살아있어 재시작 후 reattach 가능.

일반 명령 실행 (psmux 통합 불필요한 경우)

장기 세션이 아니고 단발 명령이면 psmux 우회 가능:

node scripts/wt-cli.mjs create-tab '{"title":"build","command":"npm run build","profile":"triflux"}'

profile: "triflux" 가 자동으로 psmux 를 셸로 띄우긴 하지만, command 가 즉시 종료되면 closeOnExit: "always" (wt-manager:331) 로 패인도 닫힘.

실행

scripts/wt-cli.mjs 가 wt-manager 의 thin wrapper. json-opts 는 단일 인자로 전달.

node scripts/wt-cli.mjs <action> '<json-opts>'

create-tab — 새 탭 생성

node scripts/wt-cli.mjs create-tab '{"title":"backend","command":"npm run dev","profile":"triflux","cwd":"C:\\path"}'

옵션	필수	기본
title	권장	자동
command	권장	shell
profile	선택	"triflux"
cwd	선택	현재

반환: { success, title, id? }

split-pane — 패인 분할

node scripts/wt-cli.mjs split-pane '{"direction":"H","title":"logs","command":"tail -f log"}'

옵션	값	의미
direction	"H" / "V"	가로 / 세로
title	string	패인 제목
command	string	실행할 명령

layout — 다중 패인 배치

node scripts/wt-cli.mjs layout '[{"title":"w1","command":"...","direction":"H"},{"title":"w2","command":"...","direction":"V"}]'

또는 객체 형태: '{"panes":[...]}'. dashboard / swarm worker 배치에 사용.

list — 탭 목록

node scripts/wt-cli.mjs list

반환: [{ title, id, ... }]. macOS/Linux 에서는 [].

close — 탭 닫기

node scripts/wt-cli.mjs close '{"title":"worker-1"}'

title 은 정확 일치 또는 prefix. 단일 탭 닫기.

close-stale — 오래된 탭 정리

node scripts/wt-cli.mjs close-stale '{"olderThanMs":3600000,"titlePattern":"worker-"}'

옵션	의미
olderThanMs	이 ms 이상 idle 탭만
titlePattern	title prefix 또는 regex 매칭만
dryRun	true 시 닫을 후보만 반환

반환: { success, closed: ["title-1", ...] }

rename — 탭 이름 변경

node scripts/wt-cli.mjs rename '{"title":"old","newTitle":"backend"}'

CLAUDE.md 규칙 준수

CLAUDE.md psmux-wt > wt.exe → wt-manager 경유 섹션:

차단되는 직접 호출	이 스킬 경유
wt.exe new-tab ...	create-tab
wt.exe split-pane ...	split-pane
wt.exe -w 0 sp -H ...	layout (다중) 또는 split-pane (단일)
Start-Process wt.exe ... (PowerShell)	create-tab

safety-guard 가 위 4 패턴을 모두 차단하므로 자연어 라우팅 → tfx-wt → wt-cli.mjs 가 유일한 안전 경로.

안티패턴

패턴	문제	대체
Bash("wt.exe new-tab ...")	safety-guard 차단	node scripts/wt-cli.mjs create-tab '{...}'
macOS 에서 "탭 열어" 받고 강제 실행 시도	wt-manager stub 반환 → 효과 없음 + 혼란	"Windows Terminal 미설치 환경 — no-op" 명시 후 종료
wt.exe -w 0 nt (새 창)	CLAUDE.md tfx-psmux.md RULE 5-3 금지	sp -H / sp -V (split) 사용
다중 패인을 create-tab N회 호출	새 창 N개 띄우기	layout 한 번 호출

관련

• scripts/wt-cli.mjs — CLI wrapper (이 스킬이 호출)
• hub/team/wt-manager.mjs — 실제 구현체 (createTab, splitPane, applySplitLayout, closeTab, closeStale, renameTab, listTabs)
• CLAUDE.md psmux-wt 섹션 — wt-manager API 가이드
• .claude/rules/tfx-psmux.md — psmux/WT 정책 RULE 5/6
• hooks/keyword-rules.json wt-tab-* 4 규칙 — 자연어 라우팅 진입점

메모

• PR #241 (5/8) 이후 macOS/Linux 에서도 안전. wt-manager 가 stub 반환하므로 crash 없이 no-op.
• 4/11 b313c648 커밋이 keyword-rules + wt-cli.mjs 만 추가하고 SKILL.md 를 빠뜨려 한 달간 dead 라우팅. issue #248 로 발견 후 본 스킬 추가.