OMX - Overview

시리즈: 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 네이티브 도구는 뭔가

---

• **oh-my-codex(OMX)**는 OpenAI Codex CLI를 멀티에이전트 오케스트레이션 플랫폼으로 확장하는 런타임 레이어
• Codex CLI 자체를 교체하지 않고 그 위에 조율·상태·도구 인프라를 얹는 구조
• 핵심 슬로건: “Your codex is not alone.”

해당 개념이 필요한 이유

• Codex CLI는 단일 세션 에이전트 — 한 번의 대화에서 코드 생성/수정/실행을 수행하지만, 세션 간 상태 유지나 멀티에이전트 조율 기능이 없음
• 실제 개발에서는 여러 에이전트가 역할을 나누어 병렬 작업하고, 상태를 지속 관리하며, 검증 루프를 돌려야 하는 시나리오가 빈번
• OMX는 이 간극을 메우는 오케스트레이션 런타임

AS-IS

sequenceDiagram
    autonumber
    participant U as User
    participant CX as Codex CLI

    U->>CX: "refactor the API"
    CX->>CX: 단일 세션에서 작업 수행
    CX-->>U: 결과 반환
    Note over CX: 세션 종료 시 상태 소멸
    Note over CX: 병렬 작업 불가
    Note over CX: 역할 분담 없음

TO-BE

sequenceDiagram
    autonumber
    participant U as User
    participant OMX as OMX Runtime
    participant CX1 as Codex Worker 1
    participant CX2 as Codex Worker 2
    participant MCP as MCP Servers
    participant ST as .omx/ State

    U->>OMX: "team 2:executor refactor the API"
    OMX->>MCP: 상태 초기화 (state_write)
    OMX->>CX1: frontend 리팩터 위임
    OMX->>CX2: backend 리팩터 위임
    CX1->>MCP: 진행 상태 기록
    CX2->>MCP: 진행 상태 기록
    OMX->>OMX: 검증 & 머지
    OMX->>ST: 최종 상태 저장
    OMX-->>U: 완료 보고
    Note over ST: 세션 간 상태 유지

3-Plane 아키텍처

OMX의 설계를 관통하는 핵심 구조는 세 개의 Plane으로 분리된다.

용어 출처: “Control Plane / Data(Execution) Plane”은 Kubernetes, 네트워크 아키텍처 등 인프라 분야에서 범용적으로 쓰이는 기존 용어를 차용한 것이다. OpenAI Codex 공식 용어가 아니라, OMX 저자가 자신의 설계를 설명하기 위해 적용한 OMX 고유 아키텍처 용어다.

Plane	역할	구현체	실행 주체
Control Plane	워크플로우 조율, 라이프사이클 관리, CLI	OMX CLI (src/cli/*.ts)	사람 (터미널 직접 입력) — 결정론적
Execution Plane	실제 에이전트가 코드를 생성·수정·실행	Codex CLI (AGENTS.md + 프롬프트로 작동)	LLM (AGENTS.md 해석) — 확률론적
State Plane	지속 상태, 메모리, 추적, 팀 통신	MCP 서버 5개 + .omx/ 디렉토리	Codex CLI가 config.toml 기반 자동 기동

이 분리의 핵심 이점은 Codex CLI를 실행 엔진으로 그대로 두면서, 관측성(observability)과 재개 가능성(resumability)을 OMX가 제공한다는 점이다.

주의: src/hooks/는 Control Plane인가 Execution Plane인가?

src/hooks/ 디렉토리의 스크립트(agents-overlay.ts, keyword-detector.ts 등)는 이름과 달리 Control Plane에서 실행된다. src/cli/index.ts가 이들을 import하여 omx launch 과정에서 Node.js로 호출하며, LLM(Execution Plane)이 호출하는 것이 아니다.

Codex CLI가 제공하는 것 vs OMX가 제공하는 것

Codex CLI (OpenAI 제공)

• 대화형 REPL: codex "..."
• 샌드박스: macOS Seatbelt / Linux Docker
• 승인 모드 3가지: suggest / auto-edit / full-auto
• AGENTS.md: 계층적 지침 로드 (~/.codex/AGENTS.md → ./AGENTS.md → ./subdir/AGENTS.md)
• config.toml: 모델·MCP·기능 설정
• 멀티 프로바이더: OpenAI, Azure, Gemini, Ollama 등

Seatbelt — Codex CLI의 macOS 샌드박스

Seatbelt는 macOS에 내장된 커널 레벨 샌드박스 프레임워크다. sandbox-exec 명령어로 프로세스에 보안 정책을 적용한다.

Codex CLI는 full-auto 모드에서 에이전트가 임의 명령어를 실행할 수 있기 때문에, Seatbelt로 다음을 제한한다:

허용	차단
프로젝트 디렉토리 읽기/쓰기	프로젝트 외부 디렉토리 쓰기
OpenAI API 네트워크 통신	그 외 네트워크 egress
필수 시스템 라이브러리 접근	민감 시스템 파일 접근

Linux에서는 Seatbelt 대신 Docker 컨테이너 + iptables로 동일한 격리를 구현한다. 즉 플랫폼별로 격리 메커니즘은 다르지만, “에이전트의 활동 범위를 프로젝트 안으로 가두겠다”는 목표는 같다.

OMX가 얹는 것

• omx CLI: setup, launch, team, ralph, explore, sparkshell 등 15+ 서브커맨드
• 5개 MCP 서버: state, memory, code-intel, trace, team
• 33개 Agent Prompt: architect, executor, explore 등 역할별 프롬프트
• 35+ Skill: autopilot, ralph, team, ultrawork 등 워크플로우 지침서
• Team 모드: tmux 기반 N worker 병렬 조율
• Rust 네이티브 도구: explore-harness, sparkshell

OMC(oh-my-claudecode)와의 통합 방식 차이

OMX와 OMC는 같은 목표(CLI 에이전트 확장)를 추구하지만, 대상 플랫폼의 확장 채널이 다르기 때문에 접근이 근본적으로 다르다.

항목	OMC (Claude Code)	OMX (Codex CLI)
통합 채널	Hook(stdin/stdout) + MCP + Skill tool	AGENTS.md + config.toml + CLI
이벤트 가로채기	hooks.json의 21개 공식 이벤트	AGENTS.md에 키워드 매핑 내장
에이전트 호출	Task(subagent_type="omc:executor")	/prompts:executor 또는 위임
스킬 호출	Skill("omc:ultrawork")	$ultrawork (키워드 트리거)
MCP 서버	1개 통합 서버 “t” (30+ 도구)	5개 분리 서버
Team 워커	같은 프로세스 내 서브에이전트	독립 Codex CLI 프로세스 (tmux)
네이티브 도구	없음	Rust (explore-harness, sparkshell)

왜 다른가?

• Claude Code는 Plugin 시스템과 Hook 이벤트(stdin/stdout JSON)를 공식 제공 → OMC는 이 채널을 활용
• Codex CLI는 Hook 이벤트가 없고, AGENTS.md와 config.toml이 주요 확장점 → OMX는 이 채널을 활용
• 확장 채널이 제한적이므로, OMX는 독립 CLI(omx 명령어)로 제어 레이어를 별도 구축

순차 흐름 — 요청 하나의 생명주기

사용자가 ultrawork refactor the API라고 입력하면:

1. AGENTS.md 키워드 감지 — Codex CLI가 AGENTS.md를 읽고, “ultrawork” 키워드를 감지
2. Skill 로드 — $ultrawork → skills/ultrawork/SKILL.md 읽기 → 병렬 실행 지침 context 주입
3. 에이전트 위임 — /prompts:executor로 작업 위임 → MCP를 통해 상태 기록 (state_write)
4. 상태 정리 — 완료 후 상태를 active: false로 마킹, 사용자에게 보고

OMC에서는 이 흐름이 Hook 스크립트(keyword-detector.mjs)에서 시작되지만, OMX에서는 AGENTS.md에 내장된 키워드 매핑 테이블에서 시작된다는 것이 핵심 차이다.

병렬 흐름 — Team 모드

tmux — Team 모드의 실행 기반

tmux(terminal multiplexer)는 하나의 터미널 안에서 여러 독립 셸 세션을 생성·관리하는 도구다.

┌─ tmux session: omx-team ─────────────────────┐
│ ┌─ pane 0 ──────┐ ┌─ pane 1 ──────┐         │
│ │ Worker 1      │ │ Worker 2      │         │
│ │ codex ...     │ │ codex ...     │         │
│ │ (frontend)    │ │ (backend)     │         │
│ └───────────────┘ └───────────────┘         │
│ ┌─ pane 2 ──────┐                           │
│ │ Worker 3      │                           │
│ │ codex ...     │                           │
│ │ (database)    │                           │
│ └───────────────┘                           │
└───────────────────────────────────────────────┘

OMX가 tmux를 선택한 이유:

• 각 Worker가 독립 프로세스로 실행되므로 한 Worker의 크래시가 다른 Worker에 영향을 주지 않음
• pane 캡처(tmux capture-pane)로 각 Worker의 출력을 프로그래밍적으로 읽을 수 있음
• 세션이 터미널 종료 후에도 유지되어 장시간 작업에 적합
• OMX의 sparkshell도 tmux pane 캡처를 활용하여 Worker 상태를 모니터링

Team 모드 실행 흐름

omx team 3:executor "build fullstack app" 실행 시:

1. team-plan — TeamRuntime 생성, 작업을 서브태스크로 분해
2. team-exec — tmux session 생성, 각 Worker를 독립 Codex CLI pane으로 실행
3. 병렬 실행 — Worker 1(frontend), Worker 2(backend), Worker 3(database) 동시 작업
4. team-verify — 결과 검증, 상태 업데이트, 완료 보고

Team 모드의 핵심은 각 Worker가 독립 Codex CLI 프로세스라는 점이다. OMC의 서브에이전트와 달리, tmux pane에서 완전히 격리된 프로세스로 실행된다.

디렉토리 구조 요약

디렉토리	역할	학습 파트
bin/	CLI 진입점 (omx.js)	01
src/cli/	15+ 서브커맨드 핸들러	01
src/hooks/	agents-overlay.ts, keyword-detector.ts, 세션 추적 (Control Plane — src/cli/index.ts가 import)	02
src/config/	config.toml 생성/머지	02
src/agents/	에이전트 메타데이터	04
src/mcp/	MCP 서버 5개 구현	05
src/team/	Team 모드 오케스트레이션	07
src/state/	상태 관리	06
prompts/	33개 Agent Prompt	04
skills/	35+ Skill	03
AGENTS.md	오케스트레이션 브레인	02
crates/, native/	Rust 네이티브 도구	08

참고 문서

• OMX GitHub
• Codex CLI 공식 문서
• OpenAI Codex 저장소