triflux 10.13.3 → 10.13.6

package/CLAUDE.md

@@ -0,0 +1,161 @@
+# triflux — Claude Code 운영 가이드
+
+<core-systems>
+## 핵심 스킬 시스템 (항상 인지)
+
+이 프로젝트는 3개의 스킬 시스템을 동시에 사용한다. 어떤 작업이든 해당 시스템의 스킬이 있는지 먼저 확인한다.
+
+| 시스템 | 접두사 | 용도 | 스킬 수 |
+|--------|--------|------|---------|
+| **triflux** | `/tfx-*` | CLI 라우팅, 멀티모델 오케스트레이션, 스웜, 원격 실행 | ~40개 |
+| **gstack** | `/` (접두사 없음) | QA, ship, investigate, design, review, checkpoint | ~35개 |
+| **omc** | `/oh-my-claudecode:*` | autopilot, ralph, team, ultrawork, ccg | ~25개 |
+
+스킬을 모르면 자연어 라우팅(`.claude/rules/tfx-routing.md`)으로 자동 매핑된다.
+세션 종료 전 메모리 파일이 3개+ 변경됐으면 `/memory-hygiene` 제안을 검토한다.
+</core-systems>
+
+<psmux-wt>
+## psmux/WT 규칙
+
+psmux 세션·WT 패인을 생성/조작/정리할 때 `tfx-psmux-rules` 스킬을 참조한다.
+WT 프리징 방지: exit → sleep 2 → kill 순서. 바로 kill하지 않는다.
+
+### wt.exe → wt-manager 경유
+
+safety-guard가 `wt.exe`, `wt new-tab`, `wt split-pane`, `Start-Process wt`를 차단한다.
+`hub/team/wt-manager.mjs`의 API를 사용한다.
+
+| 용도 | API |
+|------|-----|
+| 새 탭 | `createTab({ title, command, profile, cwd })` |
+| 패인 분할 | `splitPane({ direction: 'H'\|'V', title, command })` |
+| 다중 배치 | `applySplitLayout([{ title, command, direction }])` |
+| 탭 정리 | `closeTab(title)` / `closeStale({ olderThanMs, titlePattern })` |
+
+차단과 대안은 항상 쌍으로 존재해야 한다. 차단만 추가하고 대안을 안 만들면 데드락.
+
+### raw `psmux kill-session` → psmux wrapper 경유
+
+safety-guard가 raw `psmux kill-session`을 차단한다.
+세션 정리는 `hub/team/psmux.mjs` 공개 API 또는 internal wrapper로 우회한다.
+
+| 용도 | API / 래퍼 |
+|------|------------|
+| 세션 조회 | `listSessions({ filterTitle?, olderThanMs? })` |
+| title prefix / regex kill | `killSessionByTitle(titlePattern)` |
+| stale idle 세션 정리 | `pruneStale({ olderThanMs, dryRun })` |
+| Bash 훅 우회용 래퍼 | `node hub/team/psmux.mjs --internal kill-by-title <prefix\|/regex/>` |
+
+### psmux에서 Codex 실행
+
+| 방식 | 동작 | 이유 |
+|------|------|------|
+| `codex` (interactive) | 불가 | psmux에서 TTY를 못 잡음 |
+| `codex < prompt.md` | 불가 | "stdin is not a terminal" |
+| `codex exec "$(cat prompt.md)" -s danger-full-access --dangerously-bypass-approvals-and-sandbox` | 사용 | 유일한 안전 경로 |
+
+`codex exec`는 config.toml `approval_mode`를 무시하므로 `--dangerously-bypass-approvals-and-sandbox` 필수.
+`-s` 유효값: read-only, workspace-write, danger-full-access.
+</psmux-wt>
+
+<codex-config>
+## Codex config.toml
+
+config.toml에 이미 설정된 값은 CLI 플래그로 중복 지정하지 않는다.
+
+| config.toml에 있으면 | CLI에서 생략 |
+|---------------------|-------------|
+| `approval_mode = "auto"` | `-a`, `--full-auto` |
+| `sandbox = "workspace-write"` | `-s`, `--full-auto` |
+
+안전 패턴: config.toml에 기본값을 두고, CLI에서는 `--profile` 선택만 한다.
+</codex-config>
+
+<account-broker>
+## AccountBroker (계정 브로커)
+
+conductor, headless, swarm-hypervisor가 하나의 AccountBroker 싱글턴을 공유한다.
+
+| 항목 | 설명 |
+|------|------|
+| 계정별 CircuitBreaker | 장애 격리 — 한 계정 오류가 다른 계정에 전파되지 않음 |
+| busy 플래그 | 동일 계정 이중 임대(double-lease) 방지 |
+| `/broker/reload` | 장시간 세션 중 accounts.json 핫리로드 |
+| EventEmitter 이벤트 | `lease`, `release`, `cooldown`, `tierFallback`, `circuitOpen`, `circuitClose`, `noAvailableAccounts` — HUD 연동용 |
+</account-broker>
+
+<remote>
+## 원격 실행
+
+### 스킬 구분
+
+| 스킬 | 대상 | 방식 |
+|------|------|------|
+| tfx-codex-swarm | 로컬 전용 | 로컬 worktree + psmux |
+| tfx-remote-spawn | Claude Code 원격 | SSH → Claude Code 세션 → 내부 tfx 라우팅 |
+
+codex를 SSH 너머로 직접 실행하지 않는다. config.toml 충돌 + TTY 문제.
+원격에서 codex가 필요하면: remote-spawn → Claude Code → Claude가 내부에서 codex 호출.
+
+### SSH 패턴
+
+hosts.json `os` 필드로 대상 셸을 판단한다. safety-guard도 이 필드를 참조.
+
+| 대상 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>
+## Headless 결과 회수
+
+background로 실행한 headless 결과는 **반드시 task-notification 완료 후** 읽는다.
+
+| 패턴 | 올바름 | 이유 |
+|------|--------|------|
+| task-notification 후 output 파일 읽기 | YES | 프로세스 종료 = 워커 전부 완료 |
+| task-notification 전 output 파일 tail | NO | 시작 메시지만 보이고 "실패"로 오진 |
+| psmux capture-pane으로 중간 체크 | NO | 워커 진행 중이면 빈 화면일 수 있음 |
+
+완료 마커: `=== HEADLESS_COMPLETE succeeded=N failed=N total=N ===`
+워커 상세: `$TMPDIR/tfx-headless/{sessionName}-worker-N.txt`
+</headless-retrieval>
+
+<cross-review>
+## 교차 검증
+
+- Claude 작성 코드 → Codex 리뷰
+- Codex 작성 코드 → Claude 리뷰
+- 동일 모델 self-approve 하지 않는다
+- git commit 전 미검증 파일 감지 시 nudge
+</cross-review>
+
+<session-context>
+## 맥락 이탈 판단
+
+현재 세션 맥락과 무관한 요청이 감지되면 psmux 격리를 제안한다.
+
+| 확신도 | 신호 | 행동 |
+|--------|------|------|
+| 확실 | "새 탭", "별도로", "새 세션" | 바로 psmux spawn |
+| 높음 | 다른 프로젝트/스택 언급 | 분리 제안 |
+| 중간 | 작업 유형 전환 | 분리 제안 + 현재 세션 옵션 |
+| 낮음 | 현재 작업 연장 | 세션 유지 |
+</session-context>
+
+## 세부 규칙은 `.claude/rules/` 참조
+
+| 파일 | 내용 |
+|------|------|
+| `.claude/rules/tfx-routing.md` | 자연어 → 스킬 라우팅, CLI 라우팅 Layer 1~3, 충돌 해소 |
+| `.claude/rules/tfx-execution-skill-map.md` | tfx-auto / multi / swarm 실행 엔진 매핑, 격리 기준, 안티패턴 |
+| `.claude/rules/tfx-autoplan-principles.md` | gstack autoplan의 6 decision principles, phase 우선순위, 충돌 해소 규칙 추출본 |
+| `.claude/rules/tfx-update-logic.md` | triflux / OMC / gstack / Codex / Gemini 업데이트 로직 |
+| `.claude/rules/tfx-stack-coexistence.md` | gstack / superpowers / triflux 공존 원칙, 레이어 분리, 의존 방향, 충돌 해소 |
+
+Claude Code는 `.claude/rules/*.md` 를 자동 로드한다. Codex CLI는 `@import` 미지원이므로 필요 시 `AGENTS.md` 를 독립 유지한다.

package/hud/constants.mjs

@@ -79,17 +79,15 @@ export const CLAUDE_USAGE_CACHE_PATH = join(
   "cache",
   "claude-usage-cache.json",
 );
-export const PLUGIN_USAGE_CACHE_PATH = join(
+export const OMC_PLUGIN_USAGE_CACHE_PATH = join(
   homedir(),
   ".claude",
   "cache",
   "tfx-hub",
   "plugin-usage-cache.json",
 );
-export const OMC_PLUGIN_USAGE_CACHE_PATH = PLUGIN_USAGE_CACHE_PATH; // OMC alias
-export const CLAUDE_USAGE_STALE_MS_SOLO = 5 * 60 * 1000; // 플러그인 없을 때: 5분 캐시
-export const CLAUDE_USAGE_STALE_MS_WITH_PLUGIN = 15 * 60 * 1000; // 플러그인 있을 때: 15분
-export const CLAUDE_USAGE_STALE_MS_WITH_OMC = CLAUDE_USAGE_STALE_MS_WITH_PLUGIN; // OMC alias
+export const CLAUDE_USAGE_STALE_MS_SOLO = 5 * 60 * 1000; // OMC 없을 때: 5분 캐시
+export const CLAUDE_USAGE_STALE_MS_WITH_OMC = 15 * 60 * 1000; // OMC 있을 때: 15분
 export const CLAUDE_USAGE_429_BACKOFF_MS = 10 * 60 * 1000; // 429 에러 시 10분 backoff
 export const GEMINI_429_BASE_DELAY_MS = 2000;
 export const GEMINI_429_MAX_RETRIES = 3;

package/hud/providers/claude.mjs

@@ -225,12 +225,16 @@ export function parseClaudeUsageResponse(response) {
   if (!response || typeof response !== "object") return null;
   // five_hour/seven_day 키 자체가 없으면 비정상 응답
   if (!response.five_hour && !response.seven_day) return null;
-  const fiveHour = response.five_hour?.utilization;
-  const sevenDay = response.seven_day?.utilization;
-  // utilization이 null이면 0%로 처리 (API 200 성공 시 null = 사용량 없음)
+  // 키 자체가 부재하면 percent=null (HUD --% placeholder), utilization=null 만 0%로 처리
+  const fiveHourPresent = response.five_hour != null;
+  const sevenDayPresent = response.seven_day != null;
   return {
-    fiveHourPercent: clampPercent(fiveHour ?? 0),
-    weeklyPercent: clampPercent(sevenDay ?? 0),
+    fiveHourPercent: fiveHourPresent
+      ? clampPercent(response.five_hour.utilization ?? 0)
+      : null,
+    weeklyPercent: sevenDayPresent
+      ? clampPercent(response.seven_day.utilization ?? 0)
+      : null,
     fiveHourResetsAt: response.five_hour?.resets_at || null,
     weeklyResetsAt: response.seven_day?.resets_at || null,
   };

package/hud/providers/codex.mjs

@@ -18,10 +18,12 @@ import {
 import { decodeJwtEmail, readJson, writeJsonSafe } from "../utils.mjs";
 
 // window_minutes 기반 5h/1w 슬롯 분류
+// 5h: ≤360min (300min 표준, ±20% 허용)
+// weekly: ≥7000min (10080min 표준, ~5d 이상만 허용 — 24h/48h 등 중간 버킷 도입 시 silent 오분류 방지)
 export function classifyBucket(bucket) {
   if (!bucket?.window_minutes) return null;
   if (bucket.window_minutes <= 360) return "five_hour";
-  if (bucket.window_minutes >= 1440) return "weekly";
+  if (bucket.window_minutes >= 7000) return "weekly";
   return null;
 }
 

package/hud/utils.mjs

@@ -212,11 +212,13 @@ export function getContextPercent(stdin) {
 }
 
 // 과거 리셋 시간 → 다음 주기로 순환하여 미래 시점 반환
+// elapsed가 cycleMs의 정수배일 때 ceil은 target=now를 반환해 diff=0이 되므로
+// floor+1로 항상 다음 사이클을 가리키도록 한다.
 export function advanceToNextCycle(epochMs, cycleMs) {
   const now = Date.now();
   if (epochMs >= now || !cycleMs) return epochMs;
   const elapsed = now - epochMs;
-  return epochMs + Math.ceil(elapsed / cycleMs) * cycleMs;
+  return epochMs + (Math.floor(elapsed / cycleMs) + 1) * cycleMs;
 }
 
 function parseResetDate(isoOrUnix) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "10.13.3",
+  "version": "10.13.6",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {
@@ -13,77 +13,26 @@
     "tfx-doctor-tui": "bin/tfx-doctor-tui.mjs",
     "tfx-setup-tui": "bin/tfx-setup-tui.mjs"
   },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@triflux/core": "10.0.1",
+    "@triflux/remote": "^10.0.0-alpha.1"
+  },
   "files": [
     "bin",
-    "tui",
-    "hub",
-    "config",
     "skills",
-    "!skills/tfx-workspace",
-    "!**/failure-reports",
-    "scripts",
     "hooks",
     "hud",
+    "scripts",
+    "hub",
     "mesh",
-    ".claude-plugin",
+    "references",
+    "CLAUDE.md",
     "README.md",
-    "README.ko.md",
     "LICENSE"
   ],
-  "workspaces": [
-    "packages/core",
-    "packages/remote",
-    "packages/triflux"
-  ],
-  "scripts": {
-    "pack": "node scripts/pack.mjs all",
-    "pack:core": "node scripts/pack.mjs core",
-    "pack:remote": "node scripts/pack.mjs remote",
-    "setup": "node scripts/setup.mjs",
-    "preinstall": "node scripts/preinstall.mjs",
-    "postinstall": "node scripts/setup.mjs",
-    "lint": "biome check bin config hooks hub hud mesh scripts tests .claude-plugin .github package.json package-lock.json biome.json",
-    "lint:fix": "biome check --write bin config hooks hub hud mesh scripts tests .claude-plugin .github package.json package-lock.json biome.json",
-    "health": "npm test && npm run lint",
-    "test": "node scripts/test-lock.mjs --test --test-force-exit --test-concurrency=8 \"tests/**/*.test.mjs\" \"scripts/__tests__/**/*.test.mjs\"",
-    "test:unit": "node scripts/test-lock.mjs --test --test-force-exit --test-concurrency=8 tests/unit/**/*.test.mjs",
-    "test:integration": "node scripts/test-lock.mjs --test --test-force-exit --test-concurrency=8 tests/integration/**/*.test.mjs",
-    "test:route-smoke": "node scripts/test-lock.mjs --test scripts/test-tfx-route-no-claude-native.mjs",
-    "test:contract": "node scripts/test-lock.mjs --test --test-force-exit --test-concurrency=8 tests/contract/**/*.test.mjs",
-    "test:coverage": "node --experimental-test-coverage --test-coverage-lines=60 --test-coverage-functions=60 --test --test-force-exit --test-concurrency=8 \"tests/**/*.test.mjs\"",
-    "gen:skill-docs": "node scripts/gen-skill-docs.mjs",
-    "gen:skill-manifest": "node scripts/gen-skill-manifest.mjs",
-    "release:check-sync": "node scripts/release/check-sync.mjs",
-    "release:check-sync:fix": "node scripts/release/check-sync.mjs --fix",
-    "release:check-mirror": "node scripts/release/check-packages-mirror.mjs",
-    "release:check-mirror:fix": "node scripts/release/check-packages-mirror.mjs --fix",
-    "release:bump": "node scripts/release/bump-version.mjs",
-    "release:prepare": "node scripts/release/prepare.mjs",
-    "release:publish": "node scripts/release/publish.mjs",
-    "release:verify": "node scripts/release/verify.mjs"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/tellang/triflux.git"
-  },
-  "homepage": "https://github.com/tellang/triflux#readme",
-  "author": "tellang",
-  "license": "MIT",
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "better-sqlite3": "^12.6.2",
-    "pino": "^10.3.1",
-    "pino-pretty": "^13.1.3",
-    "systray2": "^2.1.4",
-    "zod": "^4.0.0"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.0.0",
-    "knip": "^6.3.0"
-  },
   "keywords": [
     "claude-code",
     "plugin",
@@ -94,5 +43,13 @@
     "multi-model",
     "triflux",
     "tfx"
-  ]
+  ],
+  "author": "tellang",
+  "license": "MIT",
+  "homepage": "https://github.com/tellang/triflux#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tellang/triflux.git",
+    "directory": "packages/triflux"
+  }
 }

package/references/cli-parameter-reference.md

@@ -0,0 +1,240 @@
+# CLI Parameter Reference — Claude Code / Codex / Gemini
+
+> 2026-04-16 기준. 공식 docs + --help + 소스코드에서 직접 수집.
+
+---
+
+## 비교 요약
+
+| 항목 | Claude Code | Codex (Rust) | Gemini |
+|------|------------|--------------|--------|
+| 최상위 플래그 | ~55개 | ~18개 | ~20개 |
+| 서브커맨드 | 10개 | 15개 | 5개 (슬래시 30+) |
+| 설정 파일 | settings.json | config.toml | settings.json |
+| 설정 키 | 100+ | 60+ | 200+ |
+| 환경변수 | 120+ | 6개 | — |
+| 비대화형 | `-p`/`--print` | `exec` 서브커맨드 | `-p`/`--prompt` |
+| 샌드박스 | settings sandbox 섹션 | `-s` 플래그 (3단계) | `--sandbox` boolean |
+| 자동승인 | `--permission-mode` | `--full-auto`/`--yolo` | `--yolo`/`--approval-mode` |
+| MCP | `claude mcp` | `codex mcp` | `/mcp` 슬래시 |
+| 모델 선택 | `--model sonnet` | `-m gpt-5.4` | `-m gemini-2.5-pro` |
+| 세션 재개 | `-r`/`--resume` | `codex resume` | `-r`/`--resume` |
+| 워크트리 | `-w`/`--worktree` | — | `-w`/`--worktree` |
+
+---
+
+## 1. Claude Code CLI
+
+### 최상위 플래그 (주요)
+
+| 플래그 | 타입 | 설명 |
+|--------|------|------|
+| `-p`/`--print` | bool | 비대화형 출력 후 종료 |
+| `--model <model>` | string | 모델 선택 (sonnet, opus, haiku) |
+| `--effort <level>` | enum | low/medium/high/max |
+| `-c`/`--continue` | bool | 최근 대화 이어가기 |
+| `-r`/`--resume` | string | 세션 ID로 재개 |
+| `--permission-mode` | enum | default/acceptEdits/plan/auto/dontAsk/bypassPermissions |
+| `--dangerously-skip-permissions` | bool | 모든 권한 확인 건너뜀 |
+| `-w`/`--worktree` | string | Git worktree 생성 |
+| `--system-prompt` | string | 시스템 프롬프트 지정 |
+| `--append-system-prompt` | string | 기본 시스템 프롬프트에 추가 |
+| `--mcp-config` | string[] | MCP 서버 JSON 설정 로드 |
+| `--max-turns` | number | 에이전트 턴 제한 (print 모드) |
+| `--max-budget-usd` | number | API 비용 상한 (print 모드) |
+| `--output-format` | enum | text/json/stream-json |
+| `--json-schema` | string | 구조화 출력 JSON Schema |
+| `--tools` | string[] | 사용 가능 도구 제한 |
+| `--allowedTools` | string[] | 허용할 도구 목록 |
+| `--disallowedTools` | string[] | 거부할 도구 목록 |
+| `--add-dir` | string[] | 추가 디렉토리 접근 허용 |
+| `--agent` | string | 세션 에이전트 지정 |
+| `--agents` | JSON | 커스텀 에이전트 정의 |
+| `--bare` | bool | 최소 모드 (hooks/LSP/plugin 건너뜀) |
+| `--fallback-model` | string | 오버로드 시 폴백 모델 |
+| `--ide` | bool | IDE 자동 연결 |
+| `--tmux` | bool | tmux 세션 생성 (--worktree 필요) |
+| `--verbose` | bool | 상세 모드 |
+| `-d`/`--debug` | string | 디버그 (카테고리 필터 가능) |
+| `--teammate-mode` | enum | auto/in-process/tmux |
+| `--remote` | string | claude.ai 웹 세션 생성 |
+| `--teleport` | bool | 웹 세션을 로컬로 가져오기 |
+
+### 서브커맨드
+
+| 커맨드 | 설명 |
+|--------|------|
+| `claude plugin` | 플러그인 관리 (install/uninstall/enable/disable/update) |
+| `claude mcp` | MCP 서버 설정 |
+| `claude config` | 인터랙티브 설정 |
+| `claude auth` | 인증 (login/logout/status) |
+| `claude agents` | 에이전트 목록 |
+| `claude doctor` | 상태 진단 |
+| `claude update` | 업데이트 |
+| `claude auto-mode` | 자동 모드 분류기 확인 |
+| `claude setup-token` | CI용 장기 토큰 생성 |
+
+### 환경변수 (주요)
+
+| 변수 | 설명 |
+|------|------|
+| `ANTHROPIC_API_KEY` | API 키 |
+| `ANTHROPIC_MODEL` | 모델 오버라이드 |
+| `ANTHROPIC_BASE_URL` | API 엔드포인트 |
+| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 최대 출력 토큰 |
+| `CLAUDE_CODE_EFFORT_LEVEL` | 노력 수준 |
+| `CLAUDE_CODE_DISABLE_THINKING` | 사고 비활성화 |
+| `CLAUDE_CODE_SUBAGENT_MODEL` | 서브에이전트 모델 |
+| `CLAUDE_CODE_USE_BEDROCK` | Bedrock 사용 |
+| `CLAUDE_CODE_USE_VERTEX` | Vertex 사용 |
+| `CLAUDE_CODE_SHELL` | 셸 오버라이드 |
+| `BASH_DEFAULT_TIMEOUT_MS` | Bash 타임아웃 (기본 120s) |
+| `API_TIMEOUT_MS` | API 타임아웃 (기본 600s) |
+
+---
+
+## 2. Codex CLI (Rust)
+
+### 최상위 플래그
+
+| 플래그 | 단축 | 타입 | 설명 |
+|--------|------|------|------|
+| `[PROMPT]` | — | string | 초기 프롬프트 |
+| `--model` | `-m` | string | 모델 (예: gpt-5.4) |
+| `--image` | `-i` | path[] | 이미지 첨부 |
+| `--sandbox` | `-s` | enum | read-only/workspace-write/danger-full-access |
+| `--ask-for-approval` | `-a` | enum | untrusted/on-request/never |
+| `--full-auto` | — | bool | workspace-write + 자동승인 |
+| `--yolo` | — | bool | 모든 제한 해제 |
+| `--profile` | `-p` | string | config.toml 프로필 |
+| `--cd` | `-C` | path | 작업 디렉토리 |
+| `--add-dir` | — | path[] | 추가 쓰기 허용 디렉토리 |
+| `--search` | — | bool | 웹 검색 활성화 |
+| `--oss` | — | bool | 로컬 LLM 사용 |
+| `--config` | `-c` | key=value | config 인라인 오버라이드 |
+| `--enable`/`--disable` | — | feature | 피처 플래그 토글 |
+
+### 서브커맨드
+
+| 커맨드 | 설명 |
+|--------|------|
+| `codex exec` | 비대화형 실행 |
+| `codex review` | 코드 리뷰 (exec review 별칭) |
+| `codex resume` | 세션 재개 (TUI) |
+| `codex fork` | 세션 분기 |
+| `codex apply` | Cloud diff 적용 |
+| `codex mcp` | MCP 서버 관리 |
+| `codex mcp-server` | Codex를 MCP 서버로 실행 |
+| `codex login`/`logout` | 인증 |
+| `codex sandbox` | 샌드박스 디버깅 |
+| `codex completion` | 셸 자동완성 |
+| `codex features` | 피처 플래그 관리 |
+
+### codex exec 플래그
+
+| 플래그 | 설명 |
+|--------|------|
+| `--json` | JSONL 이벤트 출력 |
+| `--output-last-message` | 최종 메시지 파일 저장 |
+| `--output-schema` | JSON Schema 검증 |
+| `--ephemeral` | 디스크 저장 안 함 |
+| `--skip-git-repo-check` | Git 외부 실행 허용 |
+| `--color` | always/never/auto |
+
+### codex review 플래그
+
+| 플래그 | 설명 |
+|--------|------|
+| `--uncommitted` | staged+unstaged 리뷰 |
+| `--base <branch>` | 브랜치 대비 diff 리뷰 |
+| `--commit <SHA>` | 특정 커밋 리뷰 |
+| `--title` | 리뷰 제목 |
+
+### config.toml 키 (주요)
+
+| 키 | 타입 | 설명 |
+|----|------|------|
+| `model` | string | 모델 |
+| `model_reasoning_effort` | enum | minimal/low/medium/high/xhigh |
+| `sandbox_mode` | enum | 샌드박스 정책 |
+| `approval_policy` | enum/table | 승인 정책 |
+| `shell_environment_policy.inherit` | enum | all/core/none |
+| `web_search` | enum | disabled/cached/live |
+| `mcp_servers.<id>.*` | table | MCP 서버 설정 |
+| `profiles.<name>.*` | table | 프로필별 오버라이드 |
+| `notify` | string[] | 완료 알림 명령 |
+| `features.*` | bool | 피처 플래그 |
+| `tui.*` | table | TUI 설정 |
+
+---
+
+## 3. Gemini CLI
+
+### 최상위 플래그
+
+| 플래그 | 단축 | 타입 | 설명 |
+|--------|------|------|------|
+| `[query]` | — | string | 초기 프롬프트 |
+| `--prompt` | `-p` | string | 비대화형 모드 (deprecated) |
+| `--prompt-interactive` | `-i` | string | 프롬프트 후 대화형 유지 |
+| `--model` | `-m` | string | 모델 (gemini-2.5-pro 등) |
+| `--sandbox` | `-s` | bool | 샌드박스 (Docker/Podman) |
+| `--yolo` | `-y` | bool | 모든 도구 자동승인 |
+| `--approval-mode` | — | enum | default/auto_edit/yolo/plan |
+| `--debug` | `-d` | bool | 디버그 (F12 콘솔) |
+| `--output-format` | `-o` | enum | text/json/stream-json |
+| `--resume` | `-r` | string | 세션 재개 (latest/인덱스/UUID) |
+| `--worktree` | `-w` | string | Git worktree 생성 |
+| `--extensions` | `-e` | string[] | 활성화할 익스텐션 |
+| `--include-directories` | — | string[] | 추가 디렉토리 (최대 5개) |
+| `--allowed-tools` | — | string | 확인 없이 허용할 도구 |
+| `--checkpointing` | — | bool | 파일 수정 전 스냅샷 |
+| `--screen-reader` | — | bool | 접근성 모드 |
+| `--acp` | — | bool | Agent Communication Protocol 모드 |
+| `--policy` | — | string[] | 추가 정책 파일 |
+| `--raw-output` | — | bool | ANSI 이스케이프 허용 |
+
+### 슬래시 커맨드 (주요)
+
+| 커맨드 | 설명 |
+|--------|------|
+| `/mcp list\|auth\|reload\|enable\|disable` | MCP 서버 관리 |
+| `/extensions list\|install\|update\|enable\|disable` | 익스텐션 관리 |
+| `/skills list\|enable\|disable\|reload` | 스킬 관리 |
+| `/hooks list\|enable\|disable` | 훅 관리 |
+| `/agents list\|enable\|disable\|config` | 에이전트 관리 |
+| `/model set\|manage` | 모델 전환 |
+| `/memory add\|list\|refresh` | GEMINI.md 메모리 |
+| `/chat save\|resume\|list\|share` | 세션 관리 |
+| `/compress` | 컨텍스트 압축 |
+| `/restore` | 파일 복원 |
+| `/settings` | 설정 에디터 |
+| `/stats session\|model\|tools` | 통계 |
+
+### settings.json 키 (주요 카테고리)
+
+| 카테고리 | 주요 키 |
+|---------|---------|
+| `general` | preferredEditor, vimMode, defaultApprovalMode, checkpointing, plan |
+| `model` | name, maxSessionTurns, compressionThreshold |
+| `ui` | theme, inlineThinkingMode, compactToolOutput, footer, accessibility |
+| `tools` | sandbox, shell.*, core, allowed, exclude, useRipgrep |
+| `security` | disableYoloMode, disableAlwaysAllow, folderTrust, auth |
+| `context` | fileName, includeDirectoryTree, fileFiltering, memoryBoundaryMarkers |
+| `mcpServers` | command, args, env, url, trust, includeTools, excludeTools |
+| `hooks` | BeforeTool, AfterTool, SessionStart, SessionEnd, BeforeModel |
+| `skills` | enabled, disabled |
+| `agents` | overrides, browser.* |
+| `experimental` | enableAgents, worktrees, jitContext, memoryManager |
+
+---
+
+## triflux에서의 활용
+
+| 용도 | Claude | Codex | Gemini |
+|------|--------|-------|--------|
+| 비대화형 실행 | `claude -p "prompt"` | `codex exec "prompt"` | `gemini -p "prompt"` |
+| 자동승인 | `--permission-mode bypassPermissions` | `--yolo` | `-y` |
+| JSON 출력 | `--output-format stream-json` | `--json` | `-o stream-json` |
+| MCP 연결 | `--mcp-config file.json` | config.toml `[mcp_servers]` | settings.json `mcpServers` |
+| 세션 재개 | `claude -r <id>` | `codex resume --last` | `gemini -r latest` |