OMX - OMX Integration

시리즈: oh-my-codex 아키텍처 해부

이 시리즈는 OpenAI Codex CLI 확장 런타임인 oh-my-codex(OMX)의 내부 구조를 단계별로 해부하는 과정이다.

편	내용	핵심
0편	Overview	3-Plane 아키텍처, OMC와의 차이, 전체 흐름
1편	Codex CLI Foundation	Codex CLI 자체의 구조와 확장 포인트
2편 (본문)	OMX Integration	OMX가 Codex에 어떻게 연결되나
3편	Skill System	워크플로우를 어떻게 정의하나
4편	Prompt & Agent System	에이전트는 뭐고 어떻게 선택되나
5편	MCP Servers	어떤 MCP 도구를 쓸 수 있나
6편	State & Lifecycle	상태를 어떻게 유지하나
7편	Team Orchestration	Team 모드는 어떻게 동작하나
8편	Native & Spark	Rust 네이티브 도구는 뭔가

---

• OMX Integration은 oh-my-codex가 Codex CLI의 확장 포인트에 연결되는 통합 메커니즘
• Codex CLI를 수정하지 않고 AGENTS.md, config.toml, 디렉토리 구조를 통해 행동을 주입하는 non-invasive 통합 방식
• OMC의 Hook(stdin/stdout JSON) 기반 결정론적(Deterministic) 이벤트 가로채기와 대비되는, LLM 해석에 의존하는 확률론적(Probabilistic) AGENTS.md 기반 키워드 매핑 아키텍처

해당 개념이 필요한 이유

• 1편에서 Codex CLI의 구조와 확장 포인트(AGENTS.md, config.toml, MCP)를 이해했음
• 하지만 **“OMX가 이 확장 포인트들을 실제로 어떻게 활용하는지”**가 아직 빠져 있음
• 이 파트는 OMX의 설치 흐름(omx setup), 실행 방식(omx launch), 오케스트레이션 브레인(AGENTS.md), 키워드 감지 메커니즘을 다루어 그 간극을 메움

AS-IS (OMC — Claude Code 통합 방식)

sequenceDiagram
    autonumber
    participant U as User
    participant HC as hooks.json
    participant KD as keyword-detector.mjs
    participant CC as Claude Code
    participant SK as Skill tool

    U->>CC: "ultrawork refactor API"
    CC->>HC: UserPromptSubmit 이벤트 발생
    HC->>KD: stdin JSON 전달
    KD->>KD: "ultrawork" 키워드 감지
    KD-->>HC: stdout JSON (스킬 매핑 결과)
    HC->>CC: 결과 주입
    CC->>SK: Skill("omc:ultrawork") 호출

TO-BE (OMX — Codex CLI 통합 방식)

sequenceDiagram
    autonumber
    participant U as User
    participant CX as Codex CLI
    participant AM as AGENTS.md
    participant SK as skills/ultrawork/SKILL.md

    U->>CX: "ultrawork refactor API"
    CX->>AM: 세션 시작 시 지침 로드
    Note over CX,AM: AGENTS.md에 키워드 매핑 테이블 내장
    CX->>CX: "ultrawork" 키워드 감지 (LLM이 직접 해석)
    CX->>SK: $ultrawork → SKILL.md 읽기
    CX->>CX: 스킬 지침에 따라 작업 수행

omx setup / omx launch — 실행 주체와 시점

핵심: 이 두 명령어는 AGENTS.md나 LLM이 트리거하지 않는다. 사람이 터미널에서 직접 입력하는 CLI 명령어다.

OMX는 npm으로 설치되는 Node.js CLI 도구이며, bin/omx.js가 진입점이다. src/cli/ 하위에 각 서브커맨드 핸들러가 있고, 이는 3-Plane 아키텍처의 Control Plane에 해당한다.

[사람이 터미널에서 직접 입력]
$ omx setup      ← 최초 1회, 환경 구성  (src/cli/setup.ts)
$ omx launch     ← 매 세션, Codex CLI 기동  (src/cli/launch.ts)

Plane	무엇이 실행시키나	예시
Control Plane	사람 (터미널 직접 입력)	omx setup, omx launch, omx team
Execution Plane	LLM (AGENTS.md 해석 — 확률론적)	키워드 감지, 스킬 실행, 위임
State Plane	MCP 서버 자동 동작	state_write, memory_store

AGENTS.md는 omx launch로 Codex CLI가 기동된 이후 LLM이 읽는 파일이다. omx setup/omx launch는 그 이전에 사람이 수동으로 실행하는 선행 조건이다.

sequenceDiagram
    autonumber
    participant H as 사람 (터미널)
    participant CP as Control Plane (omx CLI)
    participant CX as Codex CLI (LLM)
    participant AM as AGENTS.md

    H->>CP: omx setup (최초 1회)
    CP->>CP: AGENTS.md 생성, config.toml 등록, skills/ 배치

    H->>CP: omx launch (매 세션)
    CP->>CP: agents-overlay.ts (src/hooks/) → 세션 합본 AGENTS.md 생성
    Note over CP: user AGENTS.md + project AGENTS.md + 런타임 오버레이 머지
    CP->>CX: codex (model_instructions_file = .omx/state/{sessionId}/AGENTS.md)
    Note over CX: 네이티브 AGENTS.md 체인은 무력화됨
    CX->>CX: 세션 합본 AGENTS.md를 시스템 프롬프트로 로드 (1회)
    Note over CX: 이후 키워드 감지는 확률론적

---

omx setup — 설치 흐름

omx setup은 OMX의 모든 구성 요소를 Codex CLI가 인식하는 위치에 배치하는 부트스트래핑 명령어다. 소스는 src/cli/setup.ts.

Scope 결정: user-scope vs project-scope

항목	user-scope	project-scope
대상	전역 (모든 프로젝트)	특정 프로젝트만
AGENTS.md	~/.codex/AGENTS.md	./.codex/AGENTS.md
Skills	~/.agents/skills/	./.agents/skills/
OMX 설정	~/.omx/	./.omx/
Prompts	~/.codex/prompts/	./.codex/prompts/

설치되는 것들

graph LR
    Setup["omx setup"]

    Setup --> A["AGENTS.md 생성/머지"]
    Setup --> B["config.toml에 MCP 서버 5개 등록"]
    Setup --> C["prompts/*.md → prompts/ 디렉토리"]
    Setup --> D["skills/*/SKILL.md → skills/ 디렉토리"]
    Setup --> E["네이티브 에이전트 설정 → .omx/agents/"]

    style Setup fill:#4CAF50,color:#fff

• AGENTS.md: 기존 파일이 있으면 머지, 없으면 새로 생성
• config.toml: 5개 MCP 서버(state, memory, code-intel, trace, team) 등록
• prompts/: 33개 역할별 에이전트 프롬프트 파일 배치
• skills/: 35+ 워크플로우 스킬의 SKILL.md 파일 배치
• 네이티브 에이전트 설정: .omx/agents/에 에이전트 메타데이터 저장

omx launch — Codex를 어떤 플래그로 실행하나

omx launch는 Codex CLI를 OMX가 의도한 대로 동작시키기 위해 적절한 플래그와 환경변수를 세팅하여 실행하는 래퍼 명령어다.

핵심 설정

• model_instructions_file: agents-overlay.ts가 생성한 세션 합본 AGENTS.md(.omx/state/{sessionId}/AGENTS.md) 경로를 지정. 이 설정이 활성화되면 Codex CLI의 네이티브 AGENTS.md 계층적 머지가 무력화되므로, OMX가 직접 user/project AGENTS.md를 합쳐 넣는다.
• CODEX_HOME: project-scope일 때 프로젝트 루트의 .codex/를 가리키도록 설정

주요 플래그

플래그	동작
--yolo	Codex full-auto 모드 (승인 없이 실행)
--high / --xhigh	추론 노력(reasoning effort) 레벨 조절
--madmax	승인 우회 — 신뢰 환경 전용
--spark	Worker에 스파크 모델 사용
-w, --worktree	Git worktree 격리 모드로 실행

agents-overlay.ts — 세션별 합본 AGENTS.md 생성

agents-overlay.ts는 세션별로 공통 AGENTS.md + 런타임 오버레이를 합친 세션 전용 AGENTS.md를 생성하는 모듈이다. 소스 위치는 **src/hooks/agents-overlay.ts**이며, src/cli/index.ts가 import하여 omx launch 과정에서 호출한다. Node.js(Control Plane)가 결정론적으로 실행한다.

model_instructions_file — 공식 정의 (Codex 소스: codex-rs/core/src/config/mod.rs)

“Optional path to a file containing model instructions that will override the built-in instructions for the selected model. Users are STRONGLY DISCOURAGED from using this field, as deviating from the instructions sanctioned by Codex will likely degrade model performance.”

model_instructions_file은 config.toml의 키로, Codex 내장 모델 지침을 오버라이드하는 파일 경로를 지정한다. 우선순위: CLI 플래그 > 프로파일 > 루트 config.

핵심: model_instructions_file을 설정하면 Codex CLI의 네이티브 AGENTS.md 계층적 탐색·머지가 무력화된다 (1편 Foundation 참조: “--no-project-doc 또는 model_instructions_file로 비활성화/대체 가능”). OMX는 런타임 오버레이를 주입하기 위해 이 키를 사용하는데, 그 순간 네이티브 머지가 꺼지므로 OMX가 직접 AGENTS.md를 재머지해야 한다.

항목	model_instructions_file	AGENTS.md 네이티브 체인
역할	지정된 단일 파일을 모델 지침으로 사용	계층적 탐색·연결(concatenate)
설정 시	네이티브 AGENTS.md 체인 무력화	정상 동작
OMX 활용	세션 합본 AGENTS.md 경로 설정	omx setup이 원본 AGENTS.md에 지침 주입

실행 흐름 (소스 확인: writeSessionModelInstructionsFile())

sequenceDiagram
    autonumber
    participant H as 사람
    participant CLI as src/cli/index.ts
    participant AO as src/hooks/agents-overlay.ts
    participant UA as ~/.codex/AGENTS.md
    participant PA as {cwd}/AGENTS.md
    participant SF as .omx/state/{sessionId}/AGENTS.md
    participant CX as Codex CLI (LLM)

    H->>CLI: omx launch (Control Plane)
    CLI->>AO: writeSessionModelInstructionsFile() 호출
    AO->>UA: ① user-level AGENTS.md 읽기
    AO->>PA: ② project-level AGENTS.md 읽기
    AO->>AO: ③ project-scope 스킬 중복 참조 라인 제거
    AO->>AO: ④ ① + ② concatenate (네이티브 머지를 직접 재구현)
    AO->>AO: ⑤ + 런타임 오버레이 append
    AO->>SF: ⑥ 세션 합본 AGENTS.md 쓰기
    CLI->>CX: codex 기동 (model_instructions_file = SF 경로)
    Note over CX: 네이티브 AGENTS.md 체인은 무력화됨
    CX->>SF: 세션 시작 시 합본 파일 로드 (1회)
    Note over CX: 이후 키워드 감지는 확률론적 (Execution Plane)

원본 AGENTS.md 파일들은 수정하지 않는다. 세션이 끝나면 .omx/state/{sessionId}/AGENTS.md는 정리된다.

세션 중 동적 갱신 가능 여부

불가능하다. model_instructions_file로 지정된 파일은 세션 시작 시 1회 읽혀 시스템 프롬프트에 삽입된다. 이후 파일을 변경해도 이미 context window에 들어간 내용은 교체되지 않는다.

세션 시작 시
  AGENTS.md + 오버레이 → 시스템 프롬프트 (context window에 고정)

세션 중 파일 변경
  → context window에는 반영 안 됨 (LLM은 이미 이전 내용으로 작동 중)

MCP 툴 추가도 동일한 이유로 세션 중 반영 불가다. config.toml의 MCP 서버 목록도 Codex CLI 기동 시 로드되므로, 세션 중 MCP 서버를 추가해도 해당 세션에서는 사용할 수 없다. 변경 사항은 다음 omx launch 시 반영된다.

변경 유형	세션 중 반영	반영 시점
오버레이 파일 수정	X	다음 omx launch
AGENTS.md 수정	X	다음 omx launch
MCP 서버 추가 (config.toml)	X	다음 omx launch
MCP 툴 결과 (상태 기록 등)	O	즉시 (도구 호출 응답으로 context에 추가)

세션이 끝나면 오버레이 임시 파일은 정리된다.

AGENTS.md — 오케스트레이션 브레인

AGENTS.md는 OMX에서 “top-level operating contract for the workspace” 역할을 하는 핵심 파일이다. Codex CLI는 이 파일을 시스템 프롬프트의 일부로 로드하므로, OMX는 여기에 모든 오케스트레이션 로직을 주입한다.

Guidance Schema — 지침의 구조

docs/guidance-schema.md에 정의된 6개 섹션 구조:

섹션	역할
Role & Intent	에이전트의 역할과 목적 정의
Operating Principles	행동 원칙 5개
Execution Protocol	키워드 감지, 위임 규칙, 실행 절차
Constraints & Safety	제약 조건 및 안전 장치
Verification & Completion	작업 완료 검증 프로토콜
Recovery & Lifecycle Overlays	장애 복구 및 생명주기 오버레이

Operating Principles 5개

1. “Solve the task directly when you can do so safely and well.” — 직접 해결 우선
2. “Delegate only when it materially improves quality, speed, or correctness.” — 위임은 실질적 이점이 있을 때만
3. “Keep progress short, concrete, and useful.” — 진행 보고는 짧고 구체적으로
4. “Prefer evidence over assumption; verify before claiming completion.” — 증거 기반 검증
5. “Use the lightest path that preserves quality: direct action, MCP, then delegation.” — 경량 경로 우선 (직접 → MCP → 위임)

이 5개 원칙은 에스컬레이션 사다리를 형성한다. 에이전트는 항상 가장 가벼운 방법부터 시도하고, 필요할 때만 더 무거운 방법(MCP 호출, 다른 에이전트 위임)으로 올라간다.

Keyword Detection 테이블

AGENTS.md에 내장된 키워드 매핑 테이블은 사용자 입력에서 특정 키워드를 감지하면 어떤 스킬/에이전트를 활성화할지 정의한다. 이 테이블은 AGENTS.md 템플릿에 정적으로 하드코딩되어 있으며 (소스 확인: <keyword_detection> 섹션), keyword-registry.ts에서 동적 생성되는 것이 아니다.

키워드	우선순위	매핑 대상
ralplan	11	ralph plan 모드
autopilot	10	autopilot 스킬
ultrawork	10	ultrawork 스킬
ralph	9	ralph 에이전트
…	…	30+ 추가 키워드

Delegation Rules & Verification Protocol

• Delegation Rules: 어떤 작업을 어떤 에이전트에게 위임할지의 규칙
• Verification Protocol: 작업 완료 전 검증해야 할 항목들
• Continuation Check: 작업이 정말 끝났는지 확인하는 최종 체크

키워드 감지 — OMC Hook 방식 vs OMX AGENTS.md 방식

이 차이는 두 시스템의 아키텍처적 성격을 가장 선명하게 드러내는 지점이다.

OMC 방식: 결정론적(Deterministic) Hook 파이프라인

graph LR
    UP["UserPromptSubmit 이벤트"] --> HJ["hooks.json"]
    HJ --> KD["keyword-detector.mjs"]
    KD --> STDIN["stdin: JSON"]
    STDIN --> KD
    KD --> STDOUT["stdout: JSON"]
    STDOUT --> CC["Claude Code"]

    style KD fill:#e8f0fe

• keyword-detector.mjs가 stdin/stdout JSON 프로토콜로 이벤트를 가로챔
• Hook 스크립트가 직접 키워드를 파싱하고, 매칭 결과를 LLM 외부에서 강제 주입 → LLM의 해석 여부와 무관하게 실행됨
• 결정론적: 키워드 매칭 시 반드시 스킬이 실행됨 (LLM 판단 불개입)
• 장점: 프로그래밍 로직으로 복잡한 조건 처리 가능
• 단점: 별도 스크립트 실행 오버헤드, 디버깅 어려움

OMX 방식: 확률론적(Probabilistic) AGENTS.md 내장 + LLM 직접 해석

graph LR
    AM["AGENTS.md<br>키워드 테이블 (정적 하드코딩)"] --> CX["Codex CLI (LLM)"]
    CX --> MATCH["키워드 매칭"]
    MATCH --> SKILL["$skill → SKILL.md 로드"]

    KR["keyword-registry.ts"] -.->|"import"| KD["keyword-detector.ts<br>(프로그래밍적 2차 감지)"]

    style CX fill:#fef7e0

• AGENTS.md에 키워드 매핑 테이블이 마크다운 텍스트로 정적 하드코딩 (<keyword_detection> 섹션)
• Codex CLI의 LLM이 사용자 입력을 읽고 직접 키워드를 해석 → 강제 주입 채널 없음
• keyword-registry.ts는 AGENTS.md 주입용이 아니라, keyword-detector.ts(프로그래밍적 2차 감지)에 키워드 정의 데이터를 제공하는 모듈 (소스 확인: setup.ts에서 import하지 않음)
• 대소문자 무시, 메시지 어디에서든 매칭
• 확률론적: 키워드가 있어도 LLM이 무시하거나 다르게 해석할 수 있음 (온도·컨텍스트 포화·표현 변형 등)

keyword-detector.ts / keyword-registry.ts — 실행 시점과 역할 (소스 확인)

소스 주석 (src/hooks/keyword-detector.ts:1-12):

“In OMC, this runs as a UserPromptSubmit hook that detects magic keywords and injects skill prompts via system-reminder.” “In OMX, this logic is embedded in the AGENTS.md orchestration brain, and can also be used by the notify hook for state tracking.” “When Codex CLI adds pre-hook support, this module can be promoted to an external hook handler.”

keyword-registry.ts — 키워드 정의 데이터 모듈

• 독립 실행되지 않는다. keyword-detector.ts가 import하는 데이터 모듈일 뿐
• 58개 키워드 트리거를 { keyword, skill, priority, guidance } 형태로 export
• AGENTS.md에 주입하는 데 사용되지 않음 (setup.ts에서 import하지 않음 — 소스 확인 완료)

keyword-detector.ts — 실행 시점

OMX의 자체 Hook 시스템(src/hooks/extensibility/)이 이벤트를 발행할 때 Control Plane에서 호출된다.

• recordSkillActivation(): 사용자 입력 텍스트에서 키워드를 감지하고 skill-active-state.json에 상태 기록
• 이 상태 파일은 agents-overlay.ts가 다음 세션의 오버레이 생성 시 참조
• Codex CLI에는 UserPromptSubmit 같은 사용자 입력 가로채기 이벤트가 없으므로, 키워드를 감지해도 LLM에 결과를 강제 주입할 채널이 없음

graph LR
    KR["keyword-registry.ts<br>(데이터 모듈)"] -->|import| KD["keyword-detector.ts<br>(프로그래밍적 감지)"]
    KD -->|recordSkillActivation()| SF["skill-active-state.json"]
    SF -->|다음 세션에서 읽기| AO["agents-overlay.ts"]

    AM["AGENTS.md<br>&lt;keyword_detection&gt; 섹션"] -->|LLM이 직접 해석| CX["Codex CLI (LLM)"]

    style AM fill:#fef7e0
    style KD fill:#e8f0fe

결론: AGENTS.md가 1차 감지(확률론적, LLM 해석), keyword-detector.ts는 상태 추적용 2차 보조. OMX의 모든 스킬 실행은 결국 LLM의 판단에 의존 → 전 계층이 확률론적.

Hook 확장성 — .omx/hooks/*.mjs (소스 확인: src/hooks/extensibility/)

Codex CLI 자체에는 Hook 이벤트 시스템이 없다. 하지만 OMX는 자체 Hook 시스템을 밑바닥부터 구현하여 .omx/hooks/*.mjs 플러그인을 지원한다.

작동 원리 — Codex CLI에 Hook이 없는데 어떻게?

OMX는 두 가지 경로로 이벤트를 발행한다:

• native 이벤트: OMX의 Control Plane(src/cli/index.ts)이 Codex CLI 프로세스의 생명주기 지점에서 코드 레벨로 직접 발행 (emitNativeHookEvent() 호출). 터미널 출력을 파싱하는 것이 아님.
• derived 이벤트: 별도 백그라운드 프로세스(scripts/hook-derived-watcher.js)가 Codex CLI의 rollout JSONL 파일(~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl)을 폴링(800ms 주기)하여 파싱·추론. confidence 점수 포함 (0~1 범위). OMX_HOOK_DERIVED_SIGNALS=1 환경변수로 활성화.

graph LR
    subgraph Native ["Native 경로 (코드 레벨 직접 발행)"]
        CLI["src/cli/index.ts"] -->|"emitNativeHookEvent()"| D["dispatcher.ts"]
    end

    subgraph Derived ["Derived 경로 (rollout 파일 폴링)"]
        CX["Codex CLI"] -->|"rollout-*.jsonl 기록"| RF["~/.codex/sessions/.../rollout-*.jsonl"]
        RF -->|"800ms 폴링"| W["hook-derived-watcher.js"]
        W -->|"파싱 + 추론 (confidence)"| D
    end

    D -->|"child process spawn"| P1[".omx/hooks/plugin-a.mjs"]
    D -->|"child process spawn"| P2[".omx/hooks/plugin-b.mjs"]

    style CLI fill:#e8f0fe
    style W fill:#fef7e0

이벤트 모델 (소스: src/hooks/extensibility/types.ts, src/cli/index.ts, scripts/hook-derived-watcher.js)

types.ts에는 16개 이벤트 + open-ended 확장(string & {})이 정의되어 있다. 하지만 types.ts의 source 분류와 실제 발행 방식이 다른 경우가 있으므로, 소스 코드 기준으로 3개 그룹으로 분류한다.

Native 이벤트 — 실제 발행 확인 (소스: src/cli/index.ts:1764)

emitNativeHookEvent() 함수가 코드 레벨에서 결정론적으로 직접 발행한다. 타입 시그니처에 4개가 정의되어 있으나, 현재 실제 발행 코드가 확인된 것은 2개이다.

이벤트	감지 방식	발행 위치	비고
session-start	Codex CLI 프로세스 spawn 직후 직접 발행	index.ts:1323	context에 project 정보 포함
session-end	Codex CLI 프로세스 종료 시 cleanup에서 직접 발행	index.ts:1746	exit code로 finished/failed status 결정 후 context에 포함
session-idle	타입 시그니처에 정의됨	index.ts:1766 (시그니처)	발행 코드 미확인
turn-complete	타입 시그니처에 정의됨	index.ts:1766 (시그니처)	테스트 코드에서만 사용, 발행 코드 미확인

// src/cli/index.ts — Native 이벤트 발행 함수 (타입 시그니처에 4개 정의)
async function emitNativeHookEvent(
  cwd: string,
  event: 'session-start' | 'session-end' | 'session-idle' | 'turn-complete',
  opts: { session_id?: string; context?: Record<string, unknown>; ... } = {},
): Promise<void> {
  const payload = buildHookEvent(event, { source: 'native', context: opts.context || {} });
  await dispatchHookEvent(payload, { cwd });
}
 
// session-start 발행 (index.ts:1323) — Codex CLI spawn 직후
await emitNativeHookEvent(cwd, 'session-start', {
  session_id: sessionId,
  context: { project_path: cwd, project_name: basename(cwd), ... },
});
 
// session-end 발행 (index.ts:1746) — Codex CLI 종료 시 cleanup
const normalizedEvent = process.exitCode && process.exitCode !== 0 ? 'failed' : 'finished';
await emitNativeHookEvent(cwd, 'session-end', {
  session_id: sessionId,
  context: { status: normalizedEvent, exit_code: process.exitCode, ... },
  // ↑ finished/failed는 별도 이벤트가 아니라 session-end의 context.status로 포함
});

참고: finished와 failed는 별도 이벤트로 발행되지 않는다. session-end 이벤트의 context 내 status 필드('finished' 또는 'failed')로 포함된다.

Derived 이벤트 — 실제 발행 확인 (소스: scripts/hook-derived-watcher.js)

hook-derived-watcher.js가 Codex CLI의 rollout JSONL 파일을 폴링·파싱하여 확률론적으로 추론 발행한다. 모든 derived 이벤트는 confidence 점수를 포함한다.

이벤트	감지 방식	confidence	비고
pre-tool-use	rollout JSONL에서 tool_call_start 등 payload type 매칭	0.80	types.ts: derived
post-tool-use	rollout JSONL에서 tool_call_end 등 payload type 매칭	0.80	types.ts: derived
needs-input	assistant_message에서 질문 패턴 정규식 매칭 (?, can you, please provide 등)	0.55	types.ts: derived. 가장 낮은 confidence
test-started	exec_command가 테스트 명령어로 분류(classifyExecCommand)될 때	0.92	types.ts에서는 native로 정의되나 실제로는 derived 발행
test-finished	테스트 명령어 결과 성공 시 (result.success === true)	0.95	types.ts에서는 native로 정의되나 실제로는 derived 발행
test-failed	테스트 명령어 결과 실패 시 (result.success === false)	0.95	types.ts에서는 native로 정의되나 실제로는 derived 발행
pr-created	PR 생성 명령어 결과에서 PR 번호/URL 감지	0.97	types.ts에서는 native로 정의되나 실제로는 derived 발행

// scripts/hook-derived-watcher.js — Derived 이벤트의 핵심 감지 로직
 
// 1. rollout JSONL 파일 폴링 (800ms 주기)
const pollMs = 800;
async function pollFiles() {
  for (const [path, meta] of fileState.entries()) {
    const delta = content.slice(meta.offset);  // 마지막 읽은 위치부터 새 내용만
    for (const line of lines) { await processLine(meta, line); }
  }
}
 
// 2. pre-tool-use / post-tool-use 감지 — payload type 매칭
function inferDerivedEvent(parsed, meta) {
  if (['tool_call_start', 'tool_use_start'].includes(payloadType)) {
    return { event: 'pre-tool-use', confidence: 0.8, source: 'derived' };
  }
  if (['tool_call_end', 'tool_use_end'].includes(payloadType)) {
    return { event: 'post-tool-use', confidence: 0.8, source: 'derived' };
  }
  // 3. needs-input 감지 — 질문 패턴 정규식 (가장 낮은 confidence)
  if (payloadType === 'assistant_message') {
    const looksLikeQuestion = /\?|\b(can you|could you|please provide|need input)\b/i.test(message);
    if (looksLikeQuestion) return { event: 'needs-input', confidence: 0.55, source: 'derived' };
  }
}
 
// 4. test-started/finished/failed, pr-created 감지 — exec_command 결과 분석
function inferOperationalCall(parsed, meta) {
  if (payload.name === 'exec_command') {
    const classified = classifyExecCommand(command);  // 'test' | 'pr-create' | ...
    // test 명령어 시작 → test-started (confidence 0.92)
    // test 결과 성공  → test-finished (confidence 0.95)
    // test 결과 실패  → test-failed (confidence 0.95)
    // PR 생성 결과    → pr-created (confidence 0.97)
  }
}

types.ts 분류 vs 실제 분류 불일치: test-started, test-finished, test-failed, pr-created는 types.ts에서 native로 정의되어 있지만, 실제로는 hook-derived-watcher.js에서 buildDerivedHookEvent()로 발행한다. 이들은 rollout 파일의 exec_command 출력을 분석하여 추론하기 때문에 구조적으로 derived에 해당한다.

타입 정의만 존재 — 발행 미확인

이벤트	types.ts 분류	비고
blocked	native	발행 코드 미확인. 에러 핸들링에서 문자열로만 사용
finished	native	별도 이벤트 아님. session-end의 context status로 포함
failed	native	별도 이벤트 아님. session-end의 context status로 포함
retry-needed	native	발행 코드 미확인
handoff-needed	native	발행 코드 미확인

플러그인 SDK (HookPluginSdk)

플러그인은 onHookEvent(event, sdk) 함수를 export하며, SDK로 다음 기능을 사용할 수 있다:

SDK 메서드	기능
sdk.tmux.sendKeys()	tmux pane에 키 입력 전송
sdk.log.info/warn/error()	.omx/logs/에 로그 기록
sdk.state.read/write/delete/all()	.omx/state/에 상태 읽기/쓰기

활성화 및 비교

• OMX_HOOK_PLUGINS=1 환경변수로 활성화 (기본 비활성화)
• .omx/hooks/ 디렉토리에 .mjs 파일로 플러그인 작성
• 플러그인은 child process로 격리 실행 (timeout 지원)

비교	OMC Hook	OMX Hook
기반	Claude Code의 빌트인 Hook 시스템	OMX가 자체 구현한 Hook 시스템
이벤트 수	21개	16개 정의 (실제 발행: native 2개 + derived 7개)
Native 감지	Claude Code가 네이티브로 발행	OMX 코드가 생명주기 지점에서 직접 발행 (emitNativeHookEvent())
Derived 감지	없음 (모두 확정적)	hook-derived-watcher.js가 rollout JSONL 파일 폴링·파싱으로 추론 (confidence 포함)
활성화	hooks.json에 등록하면 자동	환경변수로 opt-in (OMX_HOOK_PLUGINS=1, derived는 OMX_HOOK_DERIVED_SIGNALS=1)
프로토콜	stdin/stdout JSON	child process spawn + SDK 주입
역할	키워드 감지의 주요 메커니즘 (결정론적)	상태 추적·모니터링 보조 메커니즘
핵심 감지	Hook 스크립트가 담당	AGENTS.md가 담당
실행 보장	결정론적 — LLM 외부에서 강제 주입	확률론적 — LLM이 판단하여 실행

참고 문서

• OMX GitHub
• Codex CLI AGENTS.md Guide
• Codex CLI config.toml Reference