triflux
CLAUDE.md7 starsChanged 13 days agoMITView on GitHub
이 프로젝트는 gstack, superpowers, triflux 3계층을 동시에 사용한다(공존 규칙은 .claude/rules/tfx-stack-coexistence.md). OMC는 호스트 스킬(deep-interview, ai-slop-cleaner 등)과 ralph·autopilot을 제공하는 보조 도구다. 어떤 작업이든 해당 시스템의 스킬이 있는지 먼저 확인한다. 주석은 한국어로 쓴다. 제거 여부는 해당 파일을 끝까지 직접 읽고 판단한다. </code-principles> macOS/Linux는 플랫폼 보호기가 아무 작업도 하지 않게 처리하므로 이 항목 자체를 건너뛰어도 된다. mac 인프라는 아래 <macos-terminal>을 참조한다. 정책·래퍼 API·Codex 호출 형태는 모두 .claude/rules/tfx-psmux.md의 규칙 1~8이 정본이다. paths에 맞는 파일을 다룰 때 로드된다. </psmux-wt> 위 <psmux-wt> 룰셋은 Windows 전용이다. macOS/Linux 환경에서…
In this repository12 other files it gives its agents.
- AGENTS.mdAGENTS.md
- tfx-autoSkill
- tfx-doctorSkill
- tfx-harnessSkill
- tfx-leadSkill
- tfx-liveSkill
- tfx-remoteSkill
- tfx-researchSkill
- tfx-reviewSkill
- tfx-setupSkill
- tfx-shipSkill
- tfx-wtSkill
The file
Files
triflux Claude Code 운영 가이드
<core-systems>
## 스킬 시스템이 프로젝트는 gstack, superpowers, triflux 3계층을 동시에 사용한다(공존 규칙은 .claude/rules/tfx-stack-coexistence.md). OMC는 호스트 스킬(deep-interview, ai-slop-cleaner 등)과 ralph·autopilot을 제공하는 보조 도구다. 어떤 작업이든 해당 시스템의 스킬이 있는지 먼저 확인한다.
| 시스템 | 접두사 | 용도 |
| triflux | /tfx-* | CLI 라우팅·다중 모델 조정·원격 실행 |
| gstack | /gstack-* | QA·출시·조사·설계·검토·점검 지점 |
| superpowers | /superpowers:* | 계획 작성·디버깅·TDD·리뷰 응답·완료 검증 |
| omc | /oh-my-claudecode:* | autopilot·ralph·team·execute·ultragoal |
</core-systems><code-principles>
## 코드 작성 원칙주석은 한국어로 쓴다. 제거 여부는 해당 파일을 끝까지 직접 읽고 판단한다.
</code-principles>
<psmux-wt>
## psmux/WT 규칙 (Windows 한정)macOS/Linux는 플랫폼 보호기가 아무 작업도 하지 않게 처리하므로 이 항목 자체를 건너뛰어도 된다. mac 인프라는
아래 <macos-terminal>을 참조한다. 정책·래퍼 API·Codex 호출 형태는 모두
.claude/rules/tfx-psmux.md의 규칙 1~8이 정본이다. paths에 맞는 파일을 다룰 때 로드된다.
</psmux-wt>
<macos-terminal>
## macOS / Linux 터미널 처리위 <psmux-wt> 룰셋은 Windows 전용이다. macOS/Linux 환경에서 triflux가 터미널/세션을 다루는 방식.
터미널 실행 경로
openCommand() 가 순차 평가하는 분기:
| 우선순위 | 조건 | 동작 | API |
| 1 | platform === "win32" | wt-manager.createTab | hub/team/wt-manager.mjs |
| 2 | isTmuxLikeMux(mux) (detectMultiplexer() → getMultiplexerType()/hasMultiplexer()/hasTmux()) | tmux new-window -n <title> <command> | 셸 직접 호출 |
| 없음 | 멀티플렉서 없음(macOS, Linux) | 미지원(false 반환) | 없음 |
터미널 관리 방식
| 후보 | 필요성 | 이유 |
| iTerm2 관리자 | 불필요 | hub/lib/env-detect.mjs의 detectTerminal이 TERM_PROGRAM === "iTerm.app"을 감지하지만 별도 GUI 패인 조작은 tmux로 처리한다. |
| tmux 관리자 | 불필요 | terminal-opener.mjs가 tmux new-window로 직접 호출한다. |
| psmux 관리자 | 이미 있음 | hub/team/psmux.mjs가 Windows에서는 psmux, macOS/Linux에서는 tmux를 사용한다. |
플랫폼 보호기
| 파일 | 함수 | 보호기 |
hub/team/wt-manager.mjs | createWtManager | if (platform() !== "win32") return createNonWindowsStubManager(); |
hub/team/headless.mjs | autoAttachTerminal | if (process.platform !== "win32") return false; + WT_SESSION 체크 |
scripts/tfx-route.sh | resolve_machine_profile_path, heartbeat_monitor | case "$(uname -s)" 분기 |
Windows 전용 경로는 플랫폼과 WT_SESSION 조건을 확인한다.
</macos-terminal>
<codex-config>
## Codex `config.toml`config.toml에 이미 설정된 값은 CLI 플래그로 중복 지정하지 않는다.
config.toml 키 | 같은 뜻의 CLI 플래그 |
approval_policy (on-request / never / granular) | --dangerously-bypass-approvals-and-sandbox |
sandbox_mode (read-only / workspace-write / danger-full-access) | -s, --sandbox |
--full-auto는 Codex 0.147에서 제거되었다. config.toml에 권한과 sandbox 기본값을 설정하고, CLI에서는 --profile <가족>과 -c 'model_reasoning_effort="<effort>"'를 지정한다.
가족 프로필은 $CODEX_HOME/<가족>.config.toml 파일이며 model만 기록한다. 인라인 [profiles.*]는 사용하지 않는다. effort는 -c model_reasoning_effort로만 전달하여 전역 effort를 덮어쓴다.
수동 CLI 예: codex -p sol -c 'model_reasoning_effort="high"'. 옛 결합 이름 파일의 병행 갱신은 이번 릴리스에 유지하고 다음 릴리스에 중단한다.
</codex-config>
<remote>
## 원격 실행스킬 구분
| 스킬 | 대상 | 방식 |
| tfx-remote | Claude Code 원격 | SSH → Claude Code 세션 → 내부 tfx 라우팅 |
Codex를 SSH 너머로 직접 실행하지 않는다. config.toml 충돌과 TTY 문제가 있다.
원격에서 Codex가 필요하면 tfx-remote → Claude Code → Claude가 내부에서 Codex를 호출한다.
SSH 패턴
hosts.json의 os 필드로 대상 셸을 판단한다.
| 대상 OS | 셸 | 패턴 |
| windows | PowerShell | scp + pwsh -File 필수. $var → $env:VAR, 2>/dev/null → 2>$null |
| darwin | zsh | 인라인 가능. brew의 PATH에 주의한다(/opt/homebrew/bin). |
| linux | bash | 인라인 가능. 표준 POSIX |
~→$HOME변환은 모든 OS 공통</remote>
<headless-retrieval>
## 비대화식 결과 회수백그라운드로 실행한 비대화식 결과는 작업 알림이 온 뒤에 읽는다.
| 패턴 | 올바름 | 이유 |
| 작업 알림 뒤 출력 파일 읽기 | 예 | 프로세스 종료 = 워커 전부 완료 |
| 작업 알림 전 출력 파일 끝부분 읽기 | 아니요 | 시작 메시지만 보이고 "실패"로 오진 |
psmux capture-pane으로 중간 확인 | 아니요 | 워커 진행 중이면 빈 화면일 수 있음 |
완료 마커: === HEADLESS_COMPLETE succeeded=N failed=N total=N ===
결과 색인: $TMPDIR/triflux-<uid>/tfx-headless/{sessionName}.results.json. 워커별 상태, exit 코드, 출력 경로는 화면 문자열 대신 이 파일을 읽는다(ADR-0034).
워커 상세: $TMPDIR/triflux-<uid>/tfx-headless/{sessionName}-worker-N.txt
triflux-<uid> 는 다른 사용자가 읽지 못하는 0700 디렉터리다. Windows 는 이 단계 없이 %TEMP%\tfx-headless 를 쓴다.
</headless-retrieval>
<native-bridge>
## 팀 실행 모드tfx multi는 tmux/psmux와 headless를 지원한다. in-process와 WT 팀 모드는 지원하지 않는다.
headless 워커도 tmux/psmux 방에서 돈다. 멀티플렉서가 없으면 모드와 관계없이 설치 안내 오류로 끝난다.
Windows Terminal의 독립 탭 열기는 유지한다.
기본 연결 UI(claude agents 노출)
워커는 tmux 방에서 돌고, claude agents 행은 그 방에 붙는 attach client다. 행에서 Enter를 누르면
워커가 도는 tmux pane이 열린다. 행은 공식 claude --bg --exec로 만든다(macOS/Linux).
| 대상 | 기본값 | 행에서 할 수 있는 것 |
tfx-auto / tfx multi headless 워커 | 켬, --no-native-bridge-ui로 끔 | 읽기 전용 관찰 |
tfx-live start 로 띄운 Claude 외 세션 | 켬 | 입력 가능. python3가 없으면 읽기 전용이고 행 이름에 [read-only]가 붙음 |
대화형 tfx multi(tmux/psmux) | 끔 | 해당 없음 |
- 행을 닫거나 Ctrl+Z로 목록에 돌아가도 워커는 계속 돈다.
- headless 워커 여럿이 한 방을 나눠 쓰면 행마다 방 전체가 보이고, 활성 pane은 행끼리 공유한다.
- 방이 사라지면 행이 스스로 지워진다. headless 실행은 끝날 때 자기가 연 행을 직접 지운다.
- 바깥 터미널의 질의 응답이 방 입력으로 새지 않게, 읽기 전용 attach 또는
hub/team/agents-row-attach.py중계를 쓴다. - 행 생성에는 cwd가 Claude에서 trust 된 워크스페이스여야 한다. 실패하면 워커는 그대로 돌고 경고만 남는다.
근거: ADR-0026.
</native-bridge>
<cross-review>
## 교차 검증- Claude 작성 코드 → Codex 리뷰
- Codex 작성 코드 → Claude 리뷰
- 동일 모델이 스스로 승인하지 않는다.
</cross-review>
<session-context>
## 맥락 이탈 판단현재 세션 맥락과 무관한 요청이 감지되면 psmux 격리를 제안한다.
| 확신도 | 신호 | 행동 |
| 확실 | "새 탭", "별도로", "새 세션" | 바로 psmux 세션 생성 |
| 높음 | 다른 프로젝트/스택 언급 | 분리 제안 |
| 중간 | 작업 유형 전환 | 분리 제안 + 현재 세션 옵션 |
| 낮음 | 현재 작업 연장 | 세션 유지 |
</session-context>세부 규칙은 .claude/rules/ 참조
| 파일 | 내용 |
.claude/rules/tfx-execution-skill-map.md | tfx-auto / multi 실행 경로와 코드 변경 병렬 작업의 worktree 격리 기준 |
.claude/rules/tfx-update-logic.md | triflux / OMC / gstack / Codex / Antigravity 업데이트 로직 |
.claude/rules/tfx-stack-coexistence.md | gstack / superpowers / triflux 공존 원칙, 레이어 분리, 의존 방향, 충돌 해소 |
.claude/rules/tfx-mirror-policy.md | packages/ 3계층 미러 정책(핵심 단순 복사 / 원격 가져오기 변환 / triflux 바이트 동일), 테스트 제외 규칙, 불일치 차단 |
.claude/rules/tfx-doc-governance.md | 실행 규칙, ADR, 설계, 계획 문서의 배치 |
.claude/rules/tfx-escalation-chain.md | 자동 재시도와 CLI 전환 체인 |
.claude/rules/tfx-machine-profile.md | 기기 프로필 우선순위와 실행 정책 |
.claude/rules/tfx-psmux.md | Windows psmux와 WT 실행 규칙 |
.claude/rules/tfx-routing.md | 역할별 CLI 라우팅과 직접 호출 제한 |
.claude/rules/tfx-skill-authoring.md | 스킬 frontmatter, 프로필 표기, 검증 규약 |
Claude Code는 .claude/rules/*.md를 paths가 맞는 파일을 다룰 때 로드한다(paths가 없는 규칙은 항상 로드된다). Codex CLI는 @import를 지원하지 않으므로 필요하면 AGENTS.md를 독립적으로 유지한다.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.