KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

oh-my-codex

★ 32,693 Open GitHub ↗

OmX - Oh My codeX: 혼자가 아닌 당신의 codex. 훅(hooks), 에이전트 팀, HUD 등 다양한 기능을 추가해 보세요.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# oh-my-codex (OMX)

![oh-my-codex character](https://yeachan-heo.github.io/oh-my-codex-website/omx-character-nobg.png)
  
*Codex를 더 강력하게 시작하고, 작업이 커지면 OMX가 더 나은 프롬프트, 워크플로우, 런타임 지원을 더하도록 하세요.*
  
  
**OmX가 마음에 들지만 약간 과하다고 느껴지시나요? [gajae-code를 사용해 보세요](https://github.com/Yeachan-Heo/gajae-code).**  
OpenClaw, Hermes, Grokbot 및 기타 통합을 위해 더 빠르고, 저렴하고, 단순하며, 강력한 SDK 기반 경로로 Codex OAuth를 유지하세요.

[![npm version](https://img.shields.io/npm/v/oh-my-codex)](https://www.npmjs.com/package/oh-my-codex)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
[![Discord](https://img.shields.io/discord/1452487457085063218?color=5865F2&logo=discord&logoColor=white&label=Discord)](https://discord.gg/jq6jnSGABY)
\*\*Website:\*\* https://yeachan-heo.github.io/oh-my-codex-website/
\*\*Docs:\*\* [Getting Started](./docs/getting-started.html) · [Agents](./docs/agents.html) · [Skills](./docs/skills.html) · [Integrations](./docs/integrations.html) · [Demo](./DEMO.md) · [OpenClaw guide](./docs/openclaw-integration.md)
\*\*Community:\*\* [Discord](https://discord.gg/jq6jnSGABY) — oh-my-codex 및 관련 도구를 위한 공유 OMX/커뮤니티 서버입니다.
## 공식 프로젝트 및 패키지
공식/오리지널 OMX 프로젝트는 이 저장소인 [`Yeachan-Heo/oh-my-codex`](https://github.com/Yeachan-Heo/oh-my-codex)이며, 이 프로젝트의 공식 npm 패키지는 [`oh-my-codex`](https://www.npmjs.com/package/oh-my-codex)입니다. `npm install -g oh-my-codex` 명령어로 이 프로젝트를 설치하세요(또는 아래에 나오는 대로 Codex CLI와 함께 설치하세요).
이 README나 문서에 명시되어 있지 않은 한, “OMX v2” 같은 이름을 사용하는 서드파티 프로젝트나 포크는 이 저장소의 공식적인 후속작, 대체품 또는 릴리스 라인이 아닙니다. 의심스러운 경우, 이 저장소와 `oh-my-codex` 패키지를 공식 설치 대상으로 신뢰하세요.
OMX는 [OpenAI Codex CLI](https://github.com/openai/codex)를 위한 워크플로우 레이어입니다.

|  |
| --- |
| **🚨 주의 — 권장 기본 환경: macOS 또는 Linux 환경의 Codex CLI.** **OMX는 주로 해당 경로를 염두에 두고 설계되었으며 적극적으로 최적화되어 있습니다.** **기본 Windows 및 Codex 앱은 기본 환경이 아니며, 작동하지 않거나 일관되지 않게 동작할 수 있고 현재 지원이 비교적 적습니다.** |

Codex를 실행 엔진으로 유지하면서 다음 작업을 더 쉽게 수행할 수 있습니다:
- 기본적으로 더 강력한 Codex 세션 시작
- 요구사항 명확화부터 완료까지 일관된 하나의 워크플로우 실행
- `$deep-interview`, `$ralplan`, `$ultragoal`을 사용하여 표준 기본 워크플로우 호출
- 프로젝트 가이드라인, 계획, 로그, 상태를 `.omx/`에 유지
## Core Maintainers
| Role | Name | GitHub |
| --- | --- | --- |
| Creator & Lead | Yeachan Heo | [@Yeachan-Heo](https://github.com/Yeachan-Heo) |
| Maintainer | Doyun Ha | [@HaD0Yun](https://github.com/HaD0Yun) |
| Maintainer | Valeriy Pavlovich | [@iqdoctor](https://github.com/iqdoctor) |
## Ambassadors
| Name | GitHub |
| --- | --- |
| Sigrid Jin | [@sigridjineth](https://github.com/sigridjineth) |
## Top Collaborators
| Name | GitHub |
| --- | --- |
| Doyun Ha | [@HaD0Yun](https://github.com/HaD0Yun) |
| Junho Yeo | [@junhoyeo](https://github.com/junhoyeo) |
| JiHongKim98 | [@JiHongKim98](https://github.com/JiHongKim98) |
| Lor | [@gobylor](https://github.com/gobylor) |
| HyunjunJeon | [@HyunjunJeon](https://github.com/HyunjunJeon) |
## Recommended default flow
기본적인 OMX 경험을 원한다면 여기서부터 시작하세요:
설치 경로 중 하나를 선택하세요. Codex CLI가 이미 설치되어 있는 경우 (Homebrew, npm 또는 기타 지원되는 방식):
```bash
codex --version
npm install -g oh-my-codex
# from the git project you want Codex to edit; choose a task-specific name
omx --worktree=feat/task --madmax --xhigh
```
Codex CLI가 아직 없고 npm으로 관리하려는 경우:
```bash
npm install -g @openai/codex
npm install -g oh-my-codex
```
`/opt/homebrew/bin/codex`와 같이 Homebrew가 관리하는 기존 `codex` 바이너리 위에 `npm install -g @openai/codex oh-my-codex`를 결합하여 실행하지 마세요. `@openai/codex`가 동일한 바이너리를 생성하려고 할 때 npm에서 `EEXIST` 오류가 발생할 수 있습니다. OMX는 `PATH` 상에서 작동하고 인증된 `codex` 명령만 필요로 하며, Codex가 반드시 npm을 통해 설치되어야 하는 것은 아닙니다.
실제 `oh-my-codex` 버전이 업그레이드될 때, 전역 npm 설치는 설정을 자동으로 실행하는 대신 명시적인 알림 텍스트를 출력합니다. 준비가 되면 아래의 범위가 지정된 설정 명령을 실행하거나 `omx update`를 사용하여 npm을 확인한 후 동일한 설정 새로고침 경로를 실행하세요.
또한 OMX는 시작할 때 제한된 주기로 npm 업데이트를 확인하고, 현재 세션이 종료된 후 업데이트 일정을 예약하기 전에 사용자에게 프롬프트를 표시합니다. 시작 시점의 확인 기능을 비활성화하려면 `OMX\_AUTO\_UPDATE=0`을 설정하고, 프롬프트 표시 없이 동일한 지연 업데이트를 예약하려면 `OMX\_AUTO\_UPDATE=defer`를 설정하세요.
설정 범위를 신중하게 선택하세요:
- 저장소가 영구적인 `AGENTS.md` 가이드라인을 소유해야 하는 경우, OMX를 작동시키려는 git 프로젝트에서 `omx setup --scope project --merge-agents`를 사용하세요.
- 현재 디렉토리를 OMX 프로젝트로 준비하는 중이 아닐 때는 사용자 수준의 Codex 설정을 위해 `omx setup --scope user`를 사용하세요.
- 해당 디렉토리가 검토 중인 프로젝트가 확실한 경우가 아니라면, 광범위한 홈 디렉토리나 운영 허브에서 프로젝트 범위의 설정을 실행하지 마세요. 홈 수준의 `AGENTS.md`에는 주로 전역 안전 및 라우팅 규칙이 포함되어 있으므로, 프로젝트별 OMX 런타임 가이드라인은 실제 저장소 내에 유지하세요.
### Persisting an explicit AGENTS merge policy
`omx setup --merge-agents`, `omx setup --no-merge-agents`, 그리고 `omx setup --clear-merge-agents-policy`는 유일한 정책 선택자입니다. 값 형태(`=value`)가 아닌 기본 형태로 사용하세요. 동일한 선택자를 반복하는 것은 무해하지만, 설정(set)과 해제(clear) 선택을 혼용하면 설정이 변경되기 전에 실패합니다. 명시적인 설정은 저장된 정책보다 우선합니다. 설정 범위가 `user`인 경우라도, 성공적인 명시적 설정은 현재 작업 루트의 `./.omx/setup-scope.json`에 `mergeAgents: true` 또는 `false`를 기록하며, 전역 사용자 기본 설정이 되거나 다른 루트로 유출되지 않습니다. 이후의 `omx update`는 즉시 새로고침과 지연 새로고침 모두에 대해 유효한 일치 정책을 다시 적용합니다.
`true`는 기존 병합 분기를 가져옵니다. `false`는 해당 분기만 억제합니다. 즉, 보존, 교체 또는 새로운 안전 모드를 보장하지 않으므로, 기존 프롬프트, 건너뛰기, 관리형 새로고침, 플러그인 기본값 및 강제 적용은 유지됩니다.

동작은 여전히 동일하게 유지됩니다. 일치하는 범위(matching-scope) 검토는 관련 없는 설정이 변경되는 동안에도 정책을 유지합니다. 재설정(Reset) 또는 범위 변경은 동일한 설정 실행에서 `true` 또는 `false`를 명시적으로 설정하지 않는 한 상속된 정책을 제거합니다. clear는 항상 정책을 제거하며 set 셀렉터와 결합할 수 없습니다. 형식이 잘못되었거나, 알 수 없거나, 부울이 아니거나, 잘못된 범위의 저장된 데이터는 안전하게 무시됩니다.
`--force`는 독립적이며 일시적입니다. 기록되지도 않고 재생되지도 않으며, 명시적인 병합 정책을 재정의하지 않습니다. 설정(Setup)은 활성 세션 또는 플러그인 심볼릭 링크 보호 장치가 현재 `AGENTS.md` 쓰기를 건너뛰는 경우를 포함하여 모든 설정 작업이 성공한 후에만 명시적인 set 또는 clear 의도를 원자적으로 커밋하므로, 다음 새로 고침에서 요청된 정책을 반영할 수 있습니다. 이것이 병합을 기본값으로 만들거나 거부된 #2892의 기본값 병합(merge-by-default) 방식을 부활시키는 것은 아닙니다. 구버전 OMX는 해당 필드를 안전하게 무시하지만, 알려진 설정 기본값을 다시 작성할 때 이를 지울 수 있습니다.

**Codex 플러그인 설치 참고 사항:** 이 저장소는 또한 `.agents/plugins/marketplace.json`의 마켓플레이스 메타데이터와 함께 `plugins/oh-my-codex`에 공식 Codex 플러그인 레이아웃을 제공합니다. 해당 플러그인은 미러링된 스킬 표면과 함께 공식 Codex 라이프사이클 훅, 선택적 MCP 호환성 서버, 그리고 앱을 위한 플러그인 범위의 컴패니언 메타데이터를 번들로 제공합니다. 이는 여전히 전역 `oh-my-codex` CLI 및 범위별 설정의 대체제가 **아닙니다**. 플러그인 범위의 훅은 설치된 `omx` CLI를 실행하고, 레거시 설정 모드는 네이티브 에이전트와 프롬프트를 설치하며, 플러그인 설정 모드는 번들 스킬에 대한 플러그인 검색에 의존하는 동시에 레거시 OMX 관리 프롬프트/네이티브 에이전트 TOML을 아카이브/제거하여 오래된 역할 파일이 플러그인 동작을 가리지 않도록 합니다. 플러그인 모드는 지속적인 오케스트레이션 지침 레이어로서 영구 범위의 `AGENTS.md`(사용자 설정의 경우 `~/.codex/AGENTS.md`, 프로젝트 설정의 경우 `./AGENTS.md`)가 여전히 필요합니다. 세션 범위의 AGENTS 파일은 해당 지속적 지침을 런타임 오버레이와 결합할 뿐이며 대체제가 아닙니다.

그런 다음 Codex 내에서 정상적으로 작업합니다:
```text
# Durable objective/checkpoints for a long task:
/goal Create a safe authentication refactor plan, implement it, and verify login, logout, and refresh-token behavior.
$deep-interview "clarify the authentication change"
$ralplan "approve the auth plan and review tradeoffs"
$prometheus-strict "stress-test the plan before durable execution"
$ultragoal "turn the approved plan into durable Codex goals"
```
이것이 주요 경로입니다.
런타임이 준비되었다고 판단하기 전에 아래의 빠른 시작 스모크 테스트를 실행하세요. `omx doctor`는 설치 형태를 검증하고, `omx exec`는 활성 Codex 런타임이 실제로 현재 환경에서 인증하고 모델 호출을 완료할 수 있음을 증명합니다.
OMX를 강력하게 시작하고, 필요할 때 먼저 명확히 하고, 계획을 승인하고, 고위험 작업 시 인터뷰 기반 계획 강화(hardening)를 위해 선택적으로 `$prometheus-strict`를 사용한 다음, 기본 영구 완료 래퍼로 `$ultragoal`을 사용하세요. 특정 Ultragoal 스토리에서 조정된 병렬 작업이 필요할 때만 해당 실행 경로 내에서 `$team`을 사용하고, 영구적인 다중 목표 실행 대신 단일 소유자 완료 루프를 의도적으로 원할 때는 `$ralph`를 사용하세요.

## OMX의 용도
이미 Codex를 좋아하고 그 주변에서 더 나은 일상적 런타임을 원한다면 OMX를 사용하세요:
- `$deep-interview` -> `$ralplan` -> `$ultragoal`을 중심으로 구축된 표준 워크플로. 계획에 실행 전 더 엄격한 인터뷰/비평/종합이 필요할 때 사용할 수 있는 `$prometheus-strict`, 그리고 선택적인 `.omx/plans/prometheus-strict/` 아티팩트
- 연구 경계: 일반적인 사전 계획 공식/업스트림 증거에는 `$best-practice-research`, 제한된 검증자 게이트 연구 아티팩트에는 `$autoresearch`, 목표 모드 연구 임무에는 `$autoresearch-goal`을 사용하고, 모든 연구 결과를 아키텍처 종합을 위해 `$ralplan`에 전달합니다.
- 계획 수립 후 기본 완료 경로로서 `$ultragoal` 및 `.omx/ultragoal` 아티팩트를 활용하는 영구 다중 목표 핸드오프
- 작업에 필요한 경우 전문가 역할 및 지원 스킬
- 범위를 지정한 `AGENTS.md`를 통한 프로젝트 지침
- 영구 통계

계획, 로그, 메모리, 모드 추적을 위해 `.omx/` 아래를 확인하세요.
추가 워크플로우 레이어 없이 일반적인 Codex만 사용하려면 아마 OMX가 필요하지 않을 것입니다.

## 빠른 시작

### 요구 사항
- Node.js 20+
- Codex CLI가 설치되어 있고, `codex --version`으로 확인되었으며, 인증된 상태 (Homebrew와 npm 모두 사용 가능합니다. Homebrew가 이미 `codex`를 관리하고 있다면 npm으로 `@openai/codex`를 재설치하지 마세요)
- Codex 인증이 설정되어 있으며 OMX를 실행할 동일한 셸/프로필에서 확인 가능해야 함
- 권장되는 안정적인 팀 런타임을 사용하려면 macOS/Linux에 `tmux` 필요
- 지원이 상대적으로 적은 Windows 팀 경로를 의도적으로 사용하려는 경우에만 네이티브 Windows에 `tmux` 대신 `psmux` 필요

### 첫 번째 세션 시작하기
설치 후 양쪽 경계를 모두 확인하세요:
```bash
omx doctor
codex login status
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"
```
`omx doctor`는 누락된 OMX 파일, 훅, 런타임 전제 조건을 찾아냅니다. 실제 스모크 테스트는 Codex가 실제 요청을 수행할 때만 나타나는 인증, 프로필, 제공자/베이스 URL 문제를 잡아냅니다.

Git 프로젝트에서 권장하는 방식으로 OMX를 실행하세요:
```bash
omx --worktree=feat/task --madmax --xhigh
```
`tmux`를 사용할 수 있는 macOS/Linux 대화형 터미널에서는 HUD/런타임 창을 생성하고 복구할 수 있도록 기본적으로 OMX가 관리하는 분리된(detached) tmux에서 리더를 시작합니다. `--worktree`는 또한 실행을 별도의 git 체크아웃으로 이동시키며, 이는 `--madmax`를 사용할 때 더 안전한 기본값입니다. `feat/task`를 작업에 맞는 브랜치 유사 이름으로 교체하세요.

### 동시 표준 대화
표준 실행은 선택된 `OMX_ROOT` 아래에 하나의 쓰기 가능한 세션 포인터를 소유합니다. 따라서 동일한 체크아웃에서 두 번째로 일반적인 `omx`를 실행하면 해당 루트를 공유하거나 조용히 변경하는 대신 실패하고 종료됩니다. 추가 대화 각각에 명시적이고 고유한 루트를 지정하세요:
```bash
omx
OMX_ROOT="$HOME/.omx/instances/second-conversation" omx
OMX_ROOT="$HOME/.omx/instances/third-conversation" omx
```
PowerShell:
```powershell
$env:OMX_ROOT = "$HOME/.omx/instances/second-conversation"
omx
```
명령 프롬프트 (Command Prompt):
```bat
set "OMX_ROOT=%USERPROFILE%\.omx\instances\second-conversation"
omx
```
사용자가 지정한 루트는 문자 그대로 적용됩니다. 동일한 명시적 `OMX_ROOT`로 두 번 실행하면 여전히 치명적인 소유자 충돌이 발생합니다. 별도의 체크아웃은 각자의 기본 루트를 가지며, `--worktree`와 `--madmax`는 기존의 격리 동작을 유지합니다.

### Madmax 및 워크트리 실행 안전성
`--madmax`는 Codex의 `--dangerously-bypass-approvals-and-sandbox`에 대한 OMX 단축키입니다. 일반적인 승인 및 샌드박스 안전 장치를 제거하므로 신뢰할 수 있는 저장소와 환경에서만 사용하세요.
`--high`와 `--xhigh`는 `-c model_reasoning_effort="high|xhigh"`의 단축키입니다. 일반적인 강력한 세션은 `omx --madmax --xhigh` (또는 Git 프로젝트 내에서 `omx --worktree=feat/task --madmax --xhigh`)입니다.

Git 저장소 내에서 `--madmax`를 사용할 때는 현재 체크아웃에서 직접 실행하는 것보다 워크트리 실행을 선호합니다. 반복 가능하거나 동시 작업의 경우 명명된 워크트리를 사용하세요:
```bash
omx --worktree=feature/auth --madmax --xhigh
```
Git 저장소 외부인 경우 `--worktree`를 생략하세요. 워크트리 실행에는 Git이 필요합니다.

동시 `--madmax` 세션의 경우, 모든 세션을 동일한 디렉터리에서 실행하지 **마세요**. 각 세션에 고유한 이름의 워크트리를 부여하세요:
```bash
omx --worktree=feature/auth --madmax --xhigh
omx --worktree=fix/flaky-tests --madmax --xhigh
```
이름이 없는 `--worktree` / `-w`는 `../.omx-worktrees/launch-detached`에 분리된 실행 워크트리를 생성하거나 재사용합니다. `--worktree=`, `--worktree `, 또는 `-w `는 `../.omx-worktrees/` 아래에 이름이 지정된 실행 워크트리를 생성하거나 재사용하고 해당 브랜치 이름을 체크아웃합니다. OMX는 Codex를 시작하기 전에 워크트리 플래그를 소비하며, Codex 자체로 전달되지 않습니다.

이름 없는 분리 형식은 일회성 편의 기능으로 취급하세요. 해당 워크트리가 생성된 후 소스 체크아웃이 진행되면, `launch-detached`가 여전히 이전 HEAD를 가리키고 있기 때문에 나중에 이름 없는 실행이 `worktree_target_mismatch`로 인해 실패할 수 있습니다. 반복 작업을 위해서는 명명된 워크트리를 사용하거나, 실행하기 전에 기존의 분리된 워크트리를 제거하세요

retry합니다.
대상 실행 worktree가 이미 dirty 상태인 경우, OMX는 경고를 표시하고 그대로 실행하므로 격리용으로 사용하기 전에 해당 worktree를 clean, commit 또는 stash 하세요.
`omx team`의 경우, 작업자들은 기본적으로 전용 worktree를 자동으로 사용합니다. `omx team`에서의 `--worktree`는 레거시 호환용 오버라이드일 뿐입니다.
리포지토리 인식 도구들은 launch, team-worker, autoresearch 런타임에서 `OMX\_REPO\_ROOT`, `OMX\_WORKTREE\_ROOT`, `OMX\_GIT\_COMMON\_DIR`, `OMX\_WORKTREE\_SCOPE`, `OMX\_CODEGRAPH\_MODE`, `OMX\_CODEGRAPH\_PROJECT\_PATH`와 같은 동일한 표준 컨텍스트를 받습니다. `OMX\_CODEGRAPH\_MODE=auto`는 worktree 로컬의 `.codegraph/codegraph.db`를 우선 탐색하고, 그 다음으로 리더/리포지토리의 `.codegraph/codegraph.db`를 확인하며, 그렇지 않으면 `off`로 해결됩니다. 명시적인 `shared`, `local`, `off` 설정도 지원됩니다. OMX는 CodeGraph를 설치하거나, worktree를 자동 인덱싱하거나, `.codegraph`를 복사/심볼릭 링크하지 않습니다. 공유 리더 인덱스는 기본 탐색에는 유용하지만 worktree 전용 변경 사항에 대해 브랜치와 정확히 일치하지는 않습니다.
OMX의 tmux/HUD 관리 없이 일회성으로 실행하려면 `--direct`를 사용하세요:
```bash
omx --direct --yolo
```
영구적인 셸/프로필 환경설정을 원한다면 환경 변수 정책을 설정하세요:
```bash
OMX\_LAUNCH\_POLICY=direct omx --yolo
```
auto/default 동작으로 돌아가려면 다음을 입력하세요:
```bash
unset OMX\_LAUNCH\_POLICY
```
CLI 정책 플래그가 환경 변수보다 우선하며, `--` 바로 앞의 마지막 CLI 정책 플래그가 적용됩니다:
```bash
OMX\_LAUNCH\_POLICY=direct omx --tmux --yolo
```
`OMX\_LAUNCH\_POLICY=direct|tmux|detached-tmux|auto`를 사용하세요. 이번 반복(iteration)에서는 CLI 및 환경 변수 제어 기능만 추가되었으며, 설정 파일(config-file) 설정은 의도적으로 추가되지 않았습니다. 기존 tmux 창 내부에서 `--direct`를 실행하면 OMX는 HUD 분할 생성, 마우스 모드 활성화, 확장 키(extended-key) 처리 래핑을 수행하지 않지만, 프로세스는 이미 열려 있는 해당 터미널 창 내부에서 계속 실행됩니다.
그런 다음 표준 워크플로우를 시도해 보세요:
```text
# 복사/붙여넣기 가능한 영구 목표 예시:
/goal 영구적인 목표, 재현을 위한 체크포인트, 구현, 회귀 테스트, 최종 검증과 함께 체크아웃 버그 수정을 배포합니다.
$ralplan "체크아웃 버그 수정 계획 승인 및 트레이드오프 검토"
$ultrawork "체크포인트 증거와 함께 승인된 체크아웃 수정 실행"
```
활성 Ultragoal 스토리에서 조율된 병렬 작업이 필요할 때는 `$team`을 사용하고, 다중 목표 원장 없이 하나의 지속적인 소유자가 완료될 때까지 계속 푸시해야 할 때는 `$ralph`를 사용하세요.
### `/goal` 및 스킬 선택
`omx --madmax --xhigh`로 정상적이고 강력한 세션을 시작하세요(또는 git 리포지토리에서 `--worktree=` 추가). 해당 세션 내에서 작업에 맞는 실행 스파인을 선택하세요: 전체 감독형 계획-실행 루프를 원할 때는 `$autopilot`, 영구 체크포인트 실행을 원할 때는 `$ultrawork`, 지속적인 소유자가 완료될 때까지 계속 밀고 나가기를 원할 때는 `$ralph`를 사용하세요. 작업 자체에 Codex가 턴마다 계속 조율해야 하는 영구적인 목표/체크포인트 구조가 필요할 때는 `/goal`을 사용하세요.
기본적으로 관련 스킬을 2~5개만 추가하세요. 작업 범위가 정당화하는 경우 더 많은 스킬이 허용되지만, 대규모 카탈로그를 로드하는 것은 보통 엄격한 파서/런타임 차단 문제가 아니라 컨텍스트 예산과 어텐션 품질의 문제입니다. 명령이 실제로 오류를 일으킬 때만 구체적인 런타임 차단 문제로 취급하세요.
안티패턴:
```text
omx --madmax --xhigh
# 그런 다음 작업을 명시하기 전에 "만약의 경우를 대비해" 즉시 20개의 스킬을 로드합니다.
# 이는 세션 컨텍스트를 비대하게 만들고 모델이 관련 없는 워크플로우에 어텐션을 낭비하게 만듭니다.
```
## 간단한 멘탈 모델
OMX는 Codex를 대체하지 \*\*않습니다\*\*.
그 주변에 더 나은 작업 레이어를 추가합니다:
- \*\*Codex\*\*는 실제 에이전트 작업을 수행합니다.
- \*\*OMX 역할 키워드\*\*는 유용한 역할을 재사용 가능하게 만듭니다.
- \*\*OMX 스킬\*\*은 공통 워크플로우를 재사용 가능하게 만듭니다.
- \*\*`.omx/`\*\*는 계획, 로그, 메모리 및 런타임 상태를 저장합니다.
대부분의 사용자는 OMX를 하루 종일 수동으로 조작하는 명령 인터페이스가 아니라, \*\*더 나은 작업 라우팅 + 더 나은 워크플로우 + 더 나은 런타임\*\*으로 생각해야 합니다.
## 처음이시라면 여기서부터 시작하세요
1. Codex CLI가 이미 존재하는 경우 `codex --version`으로 확인하고, `npm install -g oh-my-codex`로 OMX를 설치하거나 업데이트하세요.

그렇지 않으면 npm이 Codex를 관리하게 하려면 먼저 `@openai/codex`를 별도로 설치하세요.
2. 설치 후 또는 실제 OMX 버전이 올라간 경우, 대상 git 프로젝트에서 `omx setup --scope project --merge-agents`를 실행하거나 사용자 수준의 Codex 설정을 위해 `omx setup --scope user`를 실행하세요. 또는 설정을 새로고침하기 전에 npm이 최신 빌드를 확인하고 설치하도록 하려면 `omx update`를 사용하세요.
3. `omx doctor`를 실행하세요.
4. 실제 실행 스모크 테스트를 실행하세요: `codex login status` 및 `omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"`
5. git 저장소에서 명명된 워크트리를 사용하여 실행합니다. 예를 들어 `omx --worktree=feat/task --madmax --xhigh`; 동시 `--madmax` 세션을 실행하는 경우 `--worktree=feature/auth`와 같이 서로 다른 명명된 워크트리를 사용하세요.
6. 요청이나 경계가 여전히 불분명할 때 `$deep-interview "..."`를 사용하세요.
7. 계획을 승인하고 트레이드오프를 검토하기 위해 `$ralplan "..."`을 사용하세요.
8. 작업에 실행 축이 필요할 때 `$ultragoal`, `$ultrawork`, `$autopilot`, 또는 `$ralph`를 사용하세요. 지속적인 목표/체크포인트 구조를 명시해야 할 때는 `/goal`을 추가하세요.
## 권장 워크플로
1. `$deep-interview` — 요청이나 경계가 여전히 모호할 때 범위를 명확히 합니다.
2. `$ralplan` — 명확해진 범위를 승인된 아키텍처 및 구현 계획으로 전환합니다.
3. `$ultragoal` — `.omx/ultrargoal` 원장 체크포인트를 사용하여 승인된 계획을 순차적인 Codex 목표로 지속 가능하게 만듭니다.
`$ralplan`은 계획 아티팩트와 지속 가능한 합의 핸드오프에서 멈춥니다. 코드 변경에는 명시적인 실행 레인(`$ultrargoal`, `$team`, 또는 의도적인 `$ralph` 폴백)이 필요하며, ralplan은 직접 구현하지 않습니다.
Ultragoal 스토리 내부에서는 해당 스토리가 조율된 병렬 실행의 이점을 얻을 때만 `$team`을 사용하세요. 지속 가능한 다중 목표 원장이 필요하지 않을 때 의도적인 대체 완료 루프로 `$ralph`를 사용하세요.
## 일반적인 세션 내 서피스
| 서피스 | 용도 |
| --- | --- |
| `$deep-interview "..."` | 의도, 경계, 비목표(non-goal) 명확화 |
| `$ralplan "..."` | 구현 계획 및 트레이드오프 승인 |
| `$ultrargoal "..."` | 승인된 계획 이후의 지속 가능한 다중 목표 완료 |
| `$ralph "..."` | 영구적인 완료 및 검증 루프 |
| `$team "..."` | 작업 규모가 충분히 클 때의 조율된 병렬 실행 |
| `/skills` | 설치된 스킬 및 지원 헬퍼 탐색 |
| `/goal ...` | ターン(turn) 간 진행 상황을 조정해야 하는 작업을 위한 지속 가능한 목표/체크포인트 구조 |
| `omx mission ` | `.omx/missions//summary.json` 및 `ledger.jsonl` 운영자 아티팩트와 함께 `omx exec`을 통한 순차적 프롬프트/체크리스트 배치 실행 |
## 고급 / 운영자 서피스
이러한 기능들은 유용하지만, 주요 온보딩 경로는 아닙니다.
### 미션 큐 러너
각 프롬프트마다 별도의 셸 명령을 여는 대신 연속해서 실행해야 하는 OmX/Codex 프롬프트의 짧은 체크리스트가 있는 경우 `omx mission`을 사용하세요. 파싱을 검증하고 지속 가능한 요약을 검토하려면 `omx mission plan ./mission.md` 또는 `omx mission ./mission.md --dry-run`으로 시작한 다음, 프롬프트가 준비되었을 때 `omx mission run ./mission.md -- --model gpt-5`를 실행하세요. 중단된 실행은 `omx mission status ./mission.md`로 검사하고, `omx mission resume ./mission.md`로 계속 진행하며, `omx mission mark ./mission.md --task task-002 --status blocked`로 운영자 차단 상태로 만들고, `omx mission rerun ./mission.md --task task-002`로 작업별로 복구할 수 있습니다. 입력 형식, 상태 출력 및 아티팩트 세부 정보는 [`docs/mission.md`](./docs/mission.md)를 참조하세요.
### 팀 런타임
OMX 사용을 시작하는 기본 방법이 아니라, 지속 가능한 tmux/워크트리 조율이 구체적으로 필요할 때 팀 런타임을 사용하세요. Codex 앱 또는 일반적인 tmux 외부 세션에서는 `omx team`을 앱 내에서 직접 사용할 수 있는 워크플로라기보다는 tmux 런타임 셸 서피스로 취급하세요. 실제로 팀 실행을 원한다면 셸에서 OMX CLI를 먼저 실행하세요.
팀이 Ultragoal 스토리 내부에서 실행될 때, Ultragoal은 리더가 소유한 상태로 유지됩니다. 작업자들은 `.omx/ultrargoal`을 직접 변경하는 대신 체크포인트 준비 완료 증거를 상위로 보고합니다.

Team 시작은 관련 없는 작업에 대해서는 오래되었거나 잘못된 형식의 Ultragoal 아티팩트를 허용하지만, 명시적으로 Ultragoal과 연결된 Team 실행은 엄격하게 차단(fail-closed) 상태를 유지합니다. 또한 Team 시작 시 `.omx/state/team//preflight-context.json`을 기록하므로, 대규모 Team 실행은 압축(compaction) 이후에도 원래의 작업, 워커 분할, Ultragoal 컨텍스트 및 검증 체크리스트와 함께 재개할 수 있습니다.
매우 작은 원자적 작업의 경우, Team은 암시적 팬아웃을 하나의 워커로 제한하고 오버 오케스트레이션(over-orchestration) 경고를 출력할 수 있습니다. 추가 조율 비용이 의도된 경우에만 명시적인 워커 수를 전달하세요.
```bash
omx team 3:executor "fix the failing tests with verification"
omx team status 
omx team resume 
omx team shutdown 
```
### 설정, doctor 및 HUD
이러한 기능들은 운영자/지원용 인터페이스입니다:
- Codex 플러그인 마켓플레이스 설치/검색은 `${CODEX\_HOME:-~/.codex}/plugins/cache/$MARKETPLACE\_NAME/oh-my-codex/$VERSION/` 경로에 플러그인을 캐시할 수 있습니다 (로컬 설치의 경우 버전 식별자로 `local`을 사용할 수 있음). 해당 패키지된 플러그인에는 공식 Codex 생명주기 훅, 선택적 MCP 호환성 서버, 그리고 앱(MCP/앱은 기본적으로 비활성화됨)을 위한 플러그인 범위의 컴패니언 메타데이터가 포함되어 있으므로, 런타임 실행을 위해 설치된 `omx` CLI와 여전히 페어링됩니다.
- 범위가 지정된 설정(Scoped setup)은 프롬프트, 스킬, AGENTS 스캐폴딩, `.codex/config.toml`, 그리고 (레거시 설치나 `plugin\_hooks`가 없는 구형 Codex의 경우) `.codex/hooks.json` 내의 OMX 관리형 네이티브 Codex 훅을 설치합니다.
- 설정 새로 고침(setup refresh)은 `.codex/hooks.json`의 OMX 외 훅 항목을 유지하고 OMX 관리형 래퍼만 다시 작성합니다.
- 플러그인 설정은 번들로 제공되는 스킬/훅이 플러그인 캐시에서 오더라도 `AGENTS.md`를 지속적이고 영구적인 지침으로 유지합니다. 그렇지 않으면 세션 범위의 AGENTS 파일에 런타임 오버레이 지침만 포함되게 되므로, `omx doctor`는 플러그인 모드에서 지속적인 범위의 `AGENTS.md`가 누락된 경우를 실패한 검사로 처리합니다.
- `omx ` / `` 사이에 생성된 OMX 섹션을 삽입하거나 새로 고치면서 기존 프로젝트의 `AGENTS.md` 지침을 보존하며, `--no-merge-agents`는 명시적인 맥락적 비통합 선택을 기록하고, `--clear-merge-agents-policy`는 기록된 선택을 항상 제거하며 설정 셀렉터와 결합할 수 없습니다. 이 정책은 작업 루트별로 (사용자 범위의 경우에도) 저장되며, 저장된 범위가 유효하고 일치할 때만 즉시 및 지연 업데이트에 의해 재생되며, 강제/기본 정책이 되지 않습니다.
- `omx uninstall`은 `.codex/hooks.json`에서 OMX 관리형 래퍼를 제거하지만 사용자 훅이 남아 있는 경우 파일은 유지합니다.
- `omx update`는 즉시 npm을 확인하고, 최신 전역 OMX 빌드를 설치한 후, 동일한 대화형 설정 새로 고침 경로를 다시 실행합니다.
- 실행 시간 업데이트 확인은 기본적으로 속도가 제한되며 프롬프트가 표시됩니다. 비활성화하려면 `OMX\_AUTO\_UPDATE=0`을 사용하고, 프롬프트 없이 지연된 업데이트를 예약하려면 `OMX\_AUTO\_UPDATE=defer`를 사용하세요.
- 새로운 OMX 관리형 `gpt-5.6-sol` 설정 시딩은 이제 `model\_context\_window = 250000` 및 `model\_auto\_compact\_token\_limit = 200000`을 권장하지만, 해당 키가 누락된 경우에만 적용됩니다.
- `.omx-config.json` 모델/환경(env) 라우팅은 [모델/환경 라우팅 레퍼런스](./docs/reference/omx-config-schema-routing.md)에 문서화되어 있습니다. 설치된 OMX 버전에서 지원하는 키만 수정하세요.
- `omx doctor`는 문제가 있어 보일 때 설치를 확인하지만, 활성 Codex 프로필이 인증된 모델 호출을 수행할 수 있음을 증명하지는 않습니다.
- `omx hud --watch`는 기본 사용자 워크플로가 아닌 모니터링/상태 표시 인터페이스입니다.
비팀 세션의 경우, 이제 네이티브 Codex 훅이 표준 생명주기 인터페이스입니다:
- `plugins/oh-my-codex/hooks/hooks.json` = 플러그인 설치를 위한 공식 플러그인 범위 훅 등록
- `.codex/hooks.json` = 레거시 설치 및 구형 Codex 버전을 위해 유지되는 레거시/폴백 네이티브 Codex 훅 등록
- `.omx/hooks/\*.mjs` = OMX 플러그인 훅
- `omx tmux-hook` / notify-hook / 파생 감시자(derived watcher) = tmux + 런타임 폴백 경로
현재 네이티브/폴백 매트릭스는 [Codex 네이티브 훅 매핑](./docs/codex-native-hooks.md)을 참조하세요.
### 잘못된 성공(false-green) 준비 상태 문제 해결
녹색의 `omx doctor` 표시는 설치 및 위치가 정상임을 의미합니

런타임 연결 상태가 정상적인지 확인하세요. 실제 실행이 여전히 실패한다면, Codex가 실제로 사용하는 환경을 점검해 보세요:
- OMX를 실행할 동일한 셸/프로필에서 `codex login status` 및 `omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"`를 실행합니다.
- 사용자 지정 HOME, 프로필, 컨테이너 또는 서비스 셸에서는 활성화된 `~/.codex`(또는 `CODEX\_HOME`)가 예상되는 인증 및 설정이 포함된 경로인지 확인하세요. 일반 사용자 계정의 `~/.codex`가 거기서 보일 것이라고 가정해서는 안 됩니다.
- 로컬 OpenAI 호환 프록시에 의존하는 경우, 활성화된 `~/.codex/config.toml`에 예상되는 `openai\_base\_url`이 포함되어 있는지 확인하세요. 그렇지 않으면 프록시가 발급한 키가 기본 엔드포인트로 전송되어 `401 Unauthorized`, `Missing bearer or basic authentication in header`, 또는 `Incorrect API key provided` 오류로 인해 실패하게 됩니다.
- `omx doctor --team` 또는 재개(resume) 시 `resume\_blocker` 같은 오래된 팀 상태나 누락된 tmux 세션을 보고하는 경우, 재시도하기 전에 죽은 런타임 상태를 정리하세요:
```bash
omx team shutdown  --force --confirm-issues
omx cancel
omx doctor --team
```
강제 팀 종료는 이미 죽었거나 고의로 포기한 것이 확실한 팀에만 사용하세요.
OMX로 관리되는 tmux 세션 내부에서 줄바꿈을 삽입하는 대신 여전히 `Shift+Enter`로 제출되는 경우, [Troubleshooting execution readiness](./docs/troubleshooting.md#shiftenter-submits-instead-of-inserting-a-newline-in-tmux-backed-omx-sessions)를 참조하세요. 현재 버전의 OMX는 자체 Codex 실행 경로 주변에서 이미 tmux 확장 키 전달을 활성화하고 있으므로, 지속적인 실패는 대개 새로운 OMX 기능 결함이라기보다는 tmux 터미널 기능/검색 가능성 문제인 경우가 많습니다.
### Sparkshell
- `omx sparkshell`은 셸 네이티브 검사 및 제한된 검증을 위한 기능입니다.
- 읽기 전용 저장소 조회 시에는 일반적인 Codex 저장소 검사 도구/서브에이전트를 사용하세요 (지원 중단된 `omx explore` 명령어는 제거되었습니다).
- sparkshell 환경 변수 오버라이드는 의도적으로 제한되어 있습니다. `OMX\_SPARKSHELL\_BIN`은 네이티브 사이드카 경로를 선택하고, `OMX\_SPARKSHELL\_MODEL`은 기본 요약 모델을 선택하며, `OMX\_SPARKSHELL\_FALLBACK\_MODEL`은 재시도 모델을 선택하고, `OMX\_SPARKSHELL\_MODEL\_INSTRUCTIONS\_FILE`은 요약 지침을 선택하며, `OMX\_SPARKSHELL\_SUMMARY\_TIMEOUT\_MS`는 로컬 API 요약 타임아웃을 제어합니다.
예시:
```bash
omx sparkshell git status
omx sparkshell --tmux-pane %12 --tail-lines 400
```
### Wiki
- `omx wiki`는 위키 작업을 위한 CLI 중심의 JSON 인터페이스이며, `omx\_wiki` MCP는 명시적인 호환성 전용입니다.
- 위키 데이터는 `omx\_wiki/` 아래에 저장소 프로젝트 지식으로 존재합니다.
- 위키는 벡터 중심이 아니라 마크다운 중심 및 검색 중심입니다.
예시:
```bash
omx wiki list --json
omx wiki query --input '{"query":"session-start lifecycle"}' --json
omx wiki lint --json
omx wiki refresh --json
```
### 팀 모드 플랫폼 참고 사항
`omx team`은 `tmux`가 설치된 macOS/Linux에서 가장 잘 작동합니다.
네이티브 Windows는 여전히 부차적인 경로이며, Windows 기반 환경을 원하신다면 WSL2가 일반적으로 더 나은 선택입니다.
네이티브 Windows에서 OMX는 기존의 tmux 기반 경로에서 사용할 수 있는 tmux 호환 바이너리로 `psmux`를 허용합니다.
| 플랫폼 | 설치 |
| --- | --- |
| macOS | `brew install tmux` |
| Ubuntu/Debian | `sudo apt install tmux` |
| Fedora | `sudo dnf install tmux` |
| Arch | `sudo pacman -S tmux` |
| Windows | `winget install psmux` |
| Windows (WSL2) | `sudo apt install tmux` |
## 알려진 문제
### Intel Mac: 시작 시 높은 `syspolicyd` / `trustd` CPU 사용량
일부 Intel Mac에서는 OMX가 시작될 때(특히 `--madmax --high` 옵션 사용 시) macOS Gatekeeper가 동시에 발생하는 많은 프로세스 실행을 검증하면서 `syspolicyd` / `trustd`의 CPU 사용량이 급증할 수 있습니다.
이 경우 다음을 시도해 보세요:
- `xattr -dr com.apple.quarantine $(which omx)` 실행
- macOS 보안 설정의 개발자 도구(Developer Tools) 허용 목록에 터미널 앱 추가
- 낮은 동시성 사용 (예: `--madmax --high` 사용 지양)
## 문서
- [Getting Started](./docs/getting-started.html)
- [Demo guide](./DEMO.md)
- [Wiki feature](./docs/wiki-feature.md)
- [Agent catalog](./docs/agents.html)
- [Skills reference](./docs/skills.html)

[Codex 네이티브 훅 매핑](./docs/codex-native-hooks.md)
- [GitHub / PR / 패키지 신원 파이프라인](./docs/pipeline/github-pr-package-identity.md)
- [통합](./docs/integrations.html)
- [실행 준비 상태 문제 해결](./docs/troubleshooting.md)
- [OpenClaw / 알림 게이트웨이 가이드](./docs/openclaw-integration.md)
- [기여하기](./CONTRIBUTING.md)
- [변경 로그](./CHANGELOG.md)
## 언어
- [English](./README.md)
- [한국어](./docs/readme/README.ko.md)
- [日本語](./docs/readme/README.ja.md)
- [简体中文](./docs/readme/README.zh.md)
- [繁體中文](./docs/readme/README.zh-TW.md)
- [Tiếng Việt](./docs/readme/README.vi.md)
- [Español](./docs/readme/README.es.md)
- [Português](./docs/readme/README.pt.md)
- [Русский](./docs/readme/README.ru.md)
- [Türkçe](./docs/readme/README.tr.md)
- [Deutsch](./docs/readme/README.de.md)
- [Français](./docs/readme/README.fr.md)
- [Italiano](./docs/readme/README.it.md)
- [Ελληνικά](./docs/readme/README.el.md)
- [Polski](./docs/readme/README.pl.md)
- [Українська](./docs/readme/README.uk.md)
## 기여자
| 역할 | 이름 | GitHub |
| --- | --- | --- |
| 크리에이터 및 리드 | Yeachan Heo | [@Yeachan-Heo](https://github.com/Yeachan-Heo) |
| 메인테이너 | Doyun Ha | [@HaD0Yun](https://github.com/HaD0Yun) |
| 메인테이너 | Valeriy Pavlovich | [@iqdoctor](https://github.com/iqdoctor) |
## 스타 히스토리
[![Star History Chart](https://api.star-history.com/svg?repos=Yeachan-Heo/oh-my-codex&type=date&legend=top-left)](https://www.star-history.com/#Yeachan-Heo/oh-my-codex&type=date&legend=top-left)
## 라이선스
MIT
## GEO 가시성 벤치마크
OmX는 LLM 적중률, MRR, 브랜드 언급 비중(Share of Voice), 인용 횟수를 측정하기 위한 [`geobench`](https://github.com/NomaDamas/geobench) 제품 사양을 포함하고 있습니다.
- 사양: [`geobench/oh-my-codex.yaml`](geobench/oh-my-codex.yaml)
- 런북: [`docs/geobench.md`](docs/geobench.md)

oh-my-codex

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README