From hey-codex
Codex CLI로 반복 연구 루프를 운영합니다 — 목표 지향 실험을 자동으로 반복하고 결과를 기록합니다. "codex 연구", "codex research", "반복 연구", "연구 루프", "research loop", "자율 연구", "codex로 연구", "깊이 연구", "반복 실험", "autoresearch", "codex 루프", "계속 연구", "overnight research", "연구 상태 확인", "연구 이어줘", "연구 재개", "research status", "resume research" 요청에 사용합니다. 단발 작업 위임은 hey-codex가 더 적합합니다.
How this skill is triggered — by the user, by Claude, or both
Slash command
/hey-codex:codex-researchThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
<example>
Codex CLI를 반복 호출하여 목표 지향 연구 루프를 운영합니다. karpathy/autoresearch 패턴 기반.
매 라운드마다 Codex가 가설 선택 -> 변경 -> 검증 -> structured JSON 반환을 수행하고, 호스트 스크립트가 3-Layer 판단 -> git 관리 -> ledger 기록을 처리합니다.
bash "${CLAUDE_PLUGIN_ROOT}/scripts/preflight.sh"
사용자 요청을 분석하여 모드를 결정합니다.
| 모드 | 키워드 | Claude 역할 | 스크립트 역할 |
|---|---|---|---|
| design | 설계, 계약, contract, 루프 설계 | 계약 작성 | init만 |
| guided-loop (기본) | 연구 시작, 루프 시작, N라운드, 연구해줘 | 스크립트 실행 -> 결과 보고 | run --max-rounds N |
| autonomous-loop | 계속 돌려, overnight, 자율, loop-forever | 명령 발행 + 주의사항 | run --loop-forever |
키워드가 불분명하면 guided-loop을 기본으로 사용합니다.
workspace에 .codex-research/ 디렉토리 존재 여부를 확인합니다.
init 실행 + design 모드 전환 (계약 먼저 작성)contract.md 읽어서 hard gate/metric 확인 후 진행design 모드:
codex-research.sh init 실행contract.md를 사용자와 함께 작성 (references/loop-contract.md 참조)guided-loop 모드:
bash "${CLAUDE_PLUGIN_ROOT}/scripts/codex-research.sh" run <workspace> --max-rounds N --search --full-auto
실행 후 ledger.tsv + state_snapshot.md를 읽어 결과를 보고합니다.
autonomous-loop 모드:
bash "${CLAUDE_PLUGIN_ROOT}/scripts/codex-research.sh" run <workspace> --loop-forever --search --full-auto
중단 없이 실행됩니다. 반드시 경고를 표시하고, contract의 stop condition과 budget을 재확인한 뒤 명령을 발행합니다.
라운드 완료 후 다음을 보고합니다:
hard gate result, experiment status, control action을 한 칸에 섞어 쓰지 않습니다.
| 층위 | 값 | 의미 |
|---|---|---|
| hard gate result | pass / fail | 최소 통과선. fail이면 metric 개선과 무관하게 reject |
| experiment status | keep / discard / crash | best-known state 대비 이 라운드 결과를 유지할지 |
| control action | pass / refine / pivot / rescope / escalate / stop | 루프 전체 제어. 다음 라운드 방향 결정 |
루프 종료: control_action이 pass/stop/rescope/escalate이거나 max_rounds 도달.
| 기준 | hey-codex | codex-research |
|---|---|---|
| 목적 | 단발 작업 위임 | 반복 연구 루프 |
| 라운드 | 1회 | N회 |
| 상태 유지 | 없음 | program + contract + snapshot + ledger |
| 키워드 | "codex한테 시켜" | "codex로 연구해" |
라우팅: "연구/루프/반복/research/loop" 포함 -> codex-research. 없으면 -> hey-codex.
주의:
init은 workspace 디렉토리가 미리 존재해야 합니다. 새 프로젝트라면 먼저mkdir -p <workspace>후 init하세요.
# 초기화 (workspace 디렉토리는 미리 존재해야 함)
bash "${CLAUDE_PLUGIN_ROOT}/scripts/codex-research.sh" init <workspace> "objective"
# 상태 확인
bash "${CLAUDE_PLUGIN_ROOT}/scripts/codex-research.sh" status <workspace>
# 연구 실행
bash "${CLAUDE_PLUGIN_ROOT}/scripts/codex-research.sh" run <workspace> --max-rounds N --search --full-auto
shell wrapper는
<workspace>위치 인자를 내부적으로--workspace <path>로 변환합니다. 필요하면 Python runner를 직접 호출해--workspace,--state-dir같은 옵션을 명시할 수 있습니다.
| 옵션 | 기본값 | 설명 |
|---|---|---|
| --workspace | . | 연구를 수행할 workspace 디렉터리 (shell wrapper에서는 위치 인자와 동일) |
| --state-dir | <workspace>/.codex-research | 상태 파일 디렉터리 override |
| --codex-bin | codex | 사용할 Codex CLI 실행 파일 |
| --sandbox | - | read-only / workspace-write / danger-full-access |
| --max-rounds | 3 | 최대 라운드 수 |
| --loop-forever | false | 무한 실행 (autonomous-loop 전용) |
| --search | false | Codex --search (웹 검색) |
| --full-auto | false | Codex --full-auto |
| --model | - | Codex 모델 지정 |
| --timeout-seconds | 1800 | 라운드당 타임아웃 (초) |
| --skip-git-repo-check | false | Codex의 git repo 체크를 건너뜀 (non-git workspace용) |
| --commit-on-keep | auto | keep 결과 자동 commit 강제 |
| --no-commit-on-keep | false | keep 시 자동 commit 비활성화 |
| --allow-dirty | false | git dirty tree에서도 실행 허용 |
| --add-dir | - | Codex에 추가 참조 디렉토리 (반복 가능) |
--commit-on-keep: keep 결과를 항상 자동 commit 시도--no-commit-on-keep: keep 결과를 자동 commit 하지 않음. 이때 --allow-dirty가 없으면 다음 라운드 자동 진행이 중단될 수 있음.codex-research/
├── program.md # objective + 연구 범위
├── contract.md # 평가 계약 (loop-contract.md 형식)
├── state_snapshot.md # baseline, best state, 다음 후보
├── ledger.tsv # 라운드별 결과 기록
├── runtime/ # Codex 실행 중 임시 파일
└── rounds/
├── round-000/
│ ├── prompt.md
│ ├── last-message.json
│ ├── response.json
│ ├── codex-events.jsonl
│ └── evidence.md
└── round-001/...
refine 대신 pivot, rescope, escalate 우선 검토.references/loop-contract.md -- 연구 계약 작성 가이드npx claudepluginhub oozoofrog/oozoofrog-plugins --plugin hey-codexRuns Karpathy-inspired autonomous iteration loops on any task: modify, verify, keep/discard, repeat. Subcommands for planning, debugging, fixing, security audits, shipping.
Runs iterative experiments to optimize measurable metrics (speed, accuracy, config). Manages .lab/ directory for experiment history and autonomous workflow.
Orchestrates a full research-plan-implement pipeline using parallel subagents, each in its own context window, with file artifacts as the communication channel between phases.