kingbootoshi/codex-orchestrator

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) 설치:

/codex-orchestrator init

또는 "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