tmux 세션을 통해 OpenAI Codex 에이전트에게 작업을 위임합니다. Claude Code 오케스트레이션 (orchestration)을 위해 설계되었습니다.
병렬 코딩 에이전트를 생성하고, 진행 상황을 모니터링하며, 작업 중간에 후속 메시지를 보내고, 결과를 캡처할 수 있습니다. 이 모든 과정은 Claude Code 또는 명령줄 인터페이스 (CLI)에서 수행됩니다.
1단계: 마켓플레이스 (marketplace) 추가:
/plugin marketplace add kingbootoshi/codex-orchestrator
2단계: 플러그인 설치:
/plugin install codex-orchestrator
3단계: Claude Code 재시작 (스킬 (skill) 로드를 위해 필요할 수 있음)
4단계: CLI 및 의존성 (dependencies) 설치:
또는 "set up codex orchestrator"라고 말하면 Claude가 안내를 도와줄 것입니다.
5단계: 사용하기 - Claude에게 작업을 요청하기만 하면 됩니다. 코딩 작업 시 스킬이 자동으로 활성화됩니다.
Claude Code 플러그인 없이 codex-agent CLI만 사용하려는 경우:
# 필수 요구 사항 (Prerequisites)
brew install tmux # macOS (Linux의 경우 apt/pacman/dnf 사용)
npm install -g @openai/codex # OpenAI Codex CLI
...
또는 자동 설치 프로그램을 사용하세요:
bash <(curl -fsSL https://raw.githubusercontent.com/kingbootoshi/codex-orchestrator/main/plugins/codex-orchestrator/scripts/install.sh)
| 의존성 (Dependency) | 용도 | 설치 |
|---|
| tmux | 터미널 멀티플렉서 (Terminal multiplexer) - 에이전트가 tmux 세션에서 실행됨 | brew install tmux |
| ... | | |
플랫폼 지원: macOS 및 Linux. Windows 사용자는 WSL을 사용해야 합니다.
Claude Code로 작업하면서 병렬 실행, 조사 작업 또는 장시간 실행되는 작업이 필요한 경우, 백그라운드에서 Codex 에이전트를 생성하세요. 에이전트는 tmux 세션에서 실행되므로 다음과 같은 작업이 가능합니다:
실시간 모니터링 (Watch live) - 어떤 세션에도 연결하여 에이전트가 정확히 무엇을 하고 있는지 확인할 수 있습니다.
상호작용 (Talk back) - 작업 중간에 후속 메시지를 보내 방향을 수정하거나 문맥 (context)을 추가할 수 있습니다.
병렬 실행 (Run in parallel) - 코드베이스의 서로 다른 부분을 조사하는 여러 에이전트를 생성할 수 있습니다.
결과 캡처 (Capture results) - 에이전트가 완료되면 프로그래밍 방식으로 출력을 가져올 수 있습니다.
Claude는 전략적 사고(계획, 합성, 통신)를 담당합니다. Codex는 심층적인 코딩 작업(연구, 구현, 리뷰, 테스트)을 담당합니다. 이들은 함께 오케스트레이션 (Orchestration) 레이어와 실행 (Execution) 레이어를 모두 커버합니다.
--map 플래그는 모든 에이전트의 프롬프트(Prompt)에 docs/CODEBASE_MAP.md를 주입하여, 에이전트가 전체 코드베이스를 즉각적으로 이해할 수 있게 합니다: 파일의 용도, 모듈 경계, 데이터 흐름, 의존성(Dependencies), 그리고 탐색 가이드 등을 포함합니다.
맵(Map)이 없다면 에이전트는 구조를 탐색하고 추측하는 데 시간을 낭비합니다. 맵이 있다면 에이전트는 사물이 정확히 어디에 있는지 알고 즉시 작업을 시작합니다.
이 맵은 Claude Code의 보조 플러그인인 Cartographer에 의해 생성됩니다:
/plugin marketplace add kingbootoshi/cartographer
/plugin install cartographer
/cartographer
이 명령은 docs/CODEBASE_MAP.md를 생성합니다. 그 후, 모든 codex-agent start ... --map 명령은 에이전트에게 전체적인 아키텍처 컨텍스트(Architectural context)를 제공합니다. 새 프로젝트에서 codex-orchestrator를 사용하기 전에 반드시 코드베이스 맵을 생성하세요 - 이는 갈팡질팡하는 에이전트와 정밀하게 실행하는 에이전트의 차이를 만듭니다.
# 에이전트 시작
codex-agent start "Review this codebase for security vulnerabilities" --map
codex-agent start "Refactor auth module" --wait --notify-on-complete 'printf "\033[0;32mCodex agent done\033[0m\n"'
...
| 명령 | 설명 |
|---|
start <prompt> | 주어진 프롬프트로 새로운 에이전트 시작 |
status <id> | 작업 상태 및 상세 정보 확인 |
send <id> <msg> | 실행 중인 에이전트를 리다이렉트하기 위해 메시지 전송 |
capture <id> [n] | 마지막 n줄의 출력 가져오기 (기본값: 50) |
output <id> | 전체 세션 출력 가져오기 |
attach <id> | tmux attach 명령 출력 |
watch <id> | 출력 업데이트 스트리밍 |
jobs | 모든 작업 목록 표시 |
jobs --json | 구조화된 메타데이터(토큰, 파일, 요약)와 함께 작업 목록 표시 |
sessions | 활성 tmux 세션 목록 표시 |
kill <id> | 실행 중인 작업 종료 (최후의 수단) |
clean | 7일이 지난 작업 삭제 |
health | tmux 및 codex 사용 가능 여부 확인 |
| 옵션 | 설명 |
|---|
-r, --reasoning <level> | 추론 (Reasoning) 노력: low, medium, high, xhigh |
-m, --model <model> | 모델 이름 (기본값: gpt-5.4) |
-w, --wait | 완료될 때까지 대기하며, 완료 시 핑 (ping)을 발생시킴 |
--notify-on-complete <cmd> | 작업이 완료되었을 때 실행할 셸 (Shell) 명령 |
-s, --sandbox <mode> | read-only, workspace-write, danger-full-access |
-f, --file <glob> | glob 패턴과 일치하는 파일 포함 (중복 사용 가능) |
-d, --dir <path> | 작업 디렉토리 (Working directory) |
--map | 코드베이스 맵 (docs/CODEBASE_MAP.md) 포함 |
--strip-ansi | 출력에서 ANSI 제어 코드 및 Codex TUI 노이즈 제거 |
--clean | --strip-ansi의 별칭 (Alias) |
--json | JSON 출력 (jobs 명령에서만 사용 가능) |
--dry-run | 실행하지 않고 프롬프트 미리보기 |
jobs --json을 통해 구조화된 작업 데이터를 가져오세요.
:
{
"id": "8abfab85",
"status": "completed",
...
# 서로 다른 영역을 조사하기 위해 여러 에이전트(agent) 생성
codex-agent start "Audit authentication flow" -r high --map -s read-only
codex-agent start "Review database queries for N+1 issues" -r high --map -s read-only
...
# 에이전트가 잘못된 경로로 가고 있나요? 방향을 재설정하세요
codex-agent send abc123 "Stop - focus on the auth module instead"
# 에이전트에게 정보가 필요한가요? 정보를 보내세요
...
# 프롬프트에 특정 파일 포함
codex-agent start "Review these files for bugs" -f "src/auth/**/*.ts" -f "src/api/**/*.ts"
# 방향 설정을 위해 코드베이스 맵 포함
...
-
codex-agent start "task"를 실행하면
-
분리된 (detached) tmux 세션을 생성합니다.
-
해당 세션 내에서 Codex CLI를 실행합니다.
-
프롬프트를 Codex로 전송합니다.
-
작업 ID (job ID)와 함께 즉시 반환됩니다.
-
Codex는 백그라운드에서 작동합니다.
-
jobs --json, capture, output, 또는 attach를 통해 상태를 확인합니다.
-
에이전트에게 경로 수정이 필요한 경우 send로 방향을 재설정할 수 있습니다.
모든 세션 출력은 script 명령을 통해 로그로 기록되므로, 세션이 종료된 후에도 결과를 확인할 수 있습니다. 세션 메타데이터는 Codex의 JSONL 파일(~/.codex/sessions/)에서 파싱됩니다.
)를 사용하여 토큰(tokens), 파일 수정 사항(file modifications) 및 요약(summaries)을 추출합니다.
Claude Code 플러그인으로 설치하면, **codex-orchestrator 스킬 (codex-orchestrator skill)**은 Claude에게 CLI를 자동으로 사용하는 방법을 가르칩니다. Claude가 오케스트레이터(orchestrator)가 되어 다음과 같은 역할을 수행합니다:
- 사용자의 요청을 에이전트 규모의 작업(agent-sized tasks)으로 분할
- 적절한 플래그를 가진 에이전트 생성 (조사를 위한 읽기 전용(read-only), 구현을 위한 워크스페이스 쓰기(workspace-write))
- 에이전트의 진행 상황 모니터링
- 여러 에이전트로부터 얻은 결과물 합성(synthesizes)
- 작업에서 벗어난 에이전트의 방향 수정(course-corrects)
즉, 사용자는 원하는 내용을 설명하기만 하면 Claude가 위임(delegation)을 처리합니다.
이 스킬은 **아이디어 구상(Ideation) -> 조사(Research) -> 합성(Synthesis) -> 제품 요구 사항 문서(PRD) -> 구현(Implementation) -> 리뷰(Review) -> 테스트(Testing)**의 파이프라인을 따릅니다. 각 단계에서는 적절한 에이전트 설정(agent configuration)을 사용합니다.
전체 플러그인 문서는 plugins/codex-orchestrator/README.md를 참조하세요.
~/.codex-agent/jobs/
<jobId>.json # 작업 메타데이터 (Job metadata)
<jobId>.prompt # 원본 프롬프트 (Original prompt)
...
codex-agent send를 사용하여 에이전트를 리다이렉트(redirect)하세요. (에이전트를 종료하고 다시 생성하지 마세요)jobs --json을 사용하여 한 번의 호출로 구조화된 데이터(토큰, 파일, 요약)를 가져오세요.--strip-ansi (또는 --clean)를 사용하여 ANSI 및 TUI 크롬(chrome)이 제거된 파싱 친화적인(parse-friendly) 출력을 얻으세요.- 깊은 추론(deep reasoning)이 필요한 복잡한 작업에는
-r xhigh를 사용하세요.
- 에이전트에게 코드베이스 컨텍스트(codebase context)를 제공하려면
--map을 사용하세요 (docs/CODEBASE_MAP.md 필요).
- 파일을 수정해서는 안 되는 조사 작업에는
-s read-only를 사용하세요.
- 멈춰버린 작업은 최후의 수단으로만
codex-agent kill <id>를 사용하여 종료하세요.
MIT