daonhan/ralph

Ralph는 기본적으로 Claude Code를 구동하며, --agent codex로 선택하면 Codex를 사용합니다.

이는 커스텀 Docker 이미지 내부에 격리된 반복적인 구현자 → 검토자 파이프라인(implementer → reviewer pipeline)을 대상으로 하는 타깃 리포지토리에서 작동합니다.

⚠️ 보안: Ralph는 샌드박스 내부에서 선택된 에이전트를 대화형 승인 없이 실행합니다 (--permission-mode bypassPermissions (Claude의 경우); --dangerously-bypass-approvals-and-sandbox (Codex의 경우)). 또한, 기본적으로 호스트 Docker 소켓을 바인드 마운트하여 호스트 Docker 데몬에 루트 동등 접근 권한을 부여합니다. 신뢰하는 리포지토리, 플랜, GitHub 이슈에만 연결하세요. RALPH_DOCKER_SOCK=0으로 소켓 마운트를 비활성화하십시오. 전체 위협 모델은 SECURITY.md를 참조하십시오.

새로운 사용자이신가요? QUICKSTART.md(제로-투-퍼스트-루프)부터 시작하세요. Ralph 자체 해킹 → CONTRIBUTING.md. 내부 구조 → docs/ARCHITECTURE.md. 배경 / 디자인 워크스루 → The Ralph AFK Stack, Explained (Substack).

— 라이브러리: 반복 루프(iteration loop), docker 러너(docker runner), 템플릿 렌더러(template renderer), 스테이지 레지스트리(stage registry). 모든 Node 프로젝트에서 가져올 수 있습니다. @daonhan/ralph-core

— CLI: @daonhan/ralph와 ralph-afk, 그리고 ralph-ghafk 바이너리 엔트리를 노출합니다. @daonhan/ralph-core에 의존합니다.

두 가지 AFK 진입점(둘 다 npm i -g @daonhan/ralph 실행 후 전역으로 설치됨):

— 플랜/PRD 기반 루프: 여기에 플랜과 PRD 문자열을 전달하면, 에이전트가 자체 줄에 다음 신호어(ralph-afk <promise>NO MORE TASKS</promise>)를 방출할 때까지 반복합니다.
— GitHub 이슈 기반 루프: ralph-ghafk gh issue list로 열린 이슈들을 가져와 에이전트가 다음 AFK 작업을 선택하도록 합니다.

편의성 래퍼(Convenience shims)는 apps/cli/scripts/afk.sh와 apps/cli/scripts/ghafk.sh에 있습니다.
— 설치되지 않은 경우 npx @daonhan/ralph로 폴백하는 얇은 래퍼입니다.

에이전트 플레이북: packages/core/templates/prompt.md (ralph-afk용) 및 packages/core/templates/ghprompt.md (ralph-ghafk용). 검토자 지침: packages/core/templates/review.md. 이 세 가지 모두 @daonhan/ralph-core 내에 포함되어 있습니다.

ralph-afk / ralph-ghafk (npm i -g 후 PATH에 위치하는 @daonhan/ralph의 bin 항목)
│
▼
...

각 반복(iteration)은 [implementer, reviewer] 단계 체인(stage chain)을 실행합니다.

여기서 implementer는 '게이트' 역할을 합니다. 만약 <promise>NO MORE TASKS</promise>를 방출하면, reviewer가 실행되기 전에 루프가 종료됩니다.

프롬프트 템플릿은 각 단계가 실행되기 전에 순서대로 여섯 가지 태그 형태를 확장합니다 — @include: (파일 인라인 포함, 쉘 없음), @spill[?]: (명령어 실행 및 출력을 사이드 파일로 기록하는 에이전트 Read s), !?cmd|||fallback (실행 시도 - try-shell), `!`cmd (호스트 쉘 - host shell), {{ INPUTS }} (CLI의 입력 인자 — ralph-afk용 계획/PRD 문자열, ralph-ghafk는 비어 있음), 그리고 {{ HISTORY }} (.ralph/history/에서 가져온 마지막 몇 단계 결과물로, implementer 프롬프트에 주입됨). 전체 의미론(Full semantics)은 Change the template syntax에서 확인할 수 있으며, 런타임 모델은 docs/ARCHITECTURE.md에 있습니다.

ralph/
├── package.json 모노레포 루트 (private, 공유 devDeps, pnpm 스크립트)
├── pnpm-workspace.yaml
...

런타임 시, 호스트 작업 공간(host workspace)은 각 반복의 프롬프트 파일과 logs/*.ndjson을 포함하는 .ralph-tmp/ 디렉터리와, 실행당 하나의 Markdown 히스토리 파일 및 하나의 .jsonl 이벤트 로그를 담는 .ralph/history/ 디렉터리를 얻게 됩니다. 둘 다 gitignore 대상입니다 (.ralph/history/는 자체 .gitignore를 통해).

Docker — Docker Desktop (Windows/macOS) 또는 Docker Engine (Linux). 오케스트레이터가 docker build / docker run을 쉘로 실행합니다.
Node.js 20+ + npm 9+(또는 pnpm / yarn). Windows의 경우: native nvm-for-windows, nvm-windows, nodejs.org에서 직접 다운로드, 또는 WSL 내부의 Node를 사용합니다. macOS/Linux의 경우: nvm, asdf, 또는 배포판 패키지를 사용합니다. gh ralph-ghafk용으로 인증이 필요할 때만 요구됩니다: 한 번 gh auth login을 실행해야 합니다.
호스트의 git 식별자(git identity) — `git config --global user.name

자신의 것(of its own)이므로, 에이전트가 수행하는 커밋은 사용자가 작성한 것으로 간주됩니다. 리포지토리 로컬 ID는 워크스페이스 내에 설정된 것이며, 이는 git 자체의 경우와 마찬가지로 우선권을 가집니다. 어느 쪽도 없으면, Ralph는 실행당 한 번 경고하며 에이전트는 임의의 작성자를 만들 수 있습니다. Claude Code 또는 Codex를 선택한 제공업체용 인증을 사용합니다. 아래 '첫 실행 설정(First-run setup)'을 참조하십시오. (Windows, 선택 사항이지만 권장)bash.exe

PATH에 있는 경우 — Git for Windows와 함께 무료로 제공됩니다. 렌더러는 cmd.exe보다 이것을 선호하는데, 이는 POSIX 리디렉션 및 유틸리티(git log, gh issue list)가 더 원활하기 때문입니다. 만약 없다면, 렌더러는 cmd.exe로 폴백(fallback)하며 내장 try-shell 태그(!?\cmd|||fallback``)를 사용하여 명령이 실패할 경우 대체 문자열을 깨끗하게 반환합니다 — 깨진 렌더링이 없습니다.

Codex는 네이티브 Windows 셸과 WSL 모두에서 작동합니다: Ralph는 ~/.codex를 읽기 전용으로 /mnt/codex-creds에 마운트하고, 각 스테이지 전에 auth.json (그리고 존재할 경우 config.toml 및 AGENTS.md)을 컨테이너 로컬의 CODEX_HOME으로 복사합니다. 따라서 자격 증명 홈이 NTFS 기반 바인드 마운트에 놓이는 일이 없습니다. Ralph를 실행하는 것과 동일한 셸 환경에서 호스트 Codex CLI(codex login)로 로그인하십시오.

PowerShell을 통해 이미 로그인했다면 claude.exe

그리고 WSL이 해당 자격 증명도 사용하도록 하고 싶을 때:

# WSL bash — <WINUSER>를 대체하세요
mkdir -p ~/.claude
cp -r /mnt/c/Users/<WINUSER>/.claude/. ~/.claude/
...

• 전역 설치 후 PowerShell에서 Claude 실행 — 바이너리를 직접 호출하기만 하면 됩니다:
  ralph-afk "<plan-and-prd>" 3

• 또는 WSL bash 내부에서:
  ralph-afk "<plan-and-prd>" 3

Claude가 기본값으로 유지됩니다:

ralph-afk "./docs/plans/x.md ./docs/prd/x.md" 5

호출마다 Codex를 선택합니다:

ralph-afk --agent codex "./docs/plans/x.md ./docs/prd/x.md" 5
ralph-ghafk --agent codex 5

자동화를 위해, RALPH_AGENT=codex는 --agent가 없을 때의 대체값입니다.
명시적 플래그가 항상 우선합니다.

Codex는 기본적으로 ~/.codex/config.toml을 무시하지만 로그인 정보는 재사용합니다.
해당 구성을 의도적으로 로드하려면 --codex-user-config를 전달하세요. 이로 인해 구성된 MCP 서버와 훅이 시작될 수 있으므로, 해당 명령어와 경로는 Linux 샌드박스 내부에서 작동해야 합니다.

Ralph는 각 시도에 대해 모델과 추론 노력을 독립적으로 해결합니다. 플래그 및 환경 변수의 우선순위는 실행을 위해 고정되며, 제공업체 기본값과 호스트 구성은 시도가 시작될 때 읽힙니다. 각 필드에 대해 설정된 첫 번째 소스가 승리합니다 (빈 값 또는 공백만 있는 값도 설정되지 않은 것으로 간주):

--model <이름>
/--effort <레벨>

RALPH_CLAUDE_MODEL
/RALPH_CLAUDE_EFFORT
, 또는 RALPH_CODEX_MODEL
/RALPH_CODEX_EFFORT
(Codex의 경우) RALPH_MODEL
/RALPH_EFFORT
이 적용되며, 이는 어떤 에이전트가 실행되든 상관없이 적용됩니다. 에이전트 자체의 기본값이 그 아래에 있습니다.

개별 에이전트에 대한 변수 이름은 해당 에이전트의 이름에서 파생되므로, 두 에이전트를 한 번에 구성할 수 있으며 에이전트를 전환해도 서로의 모델을 보내지 않습니다.

모든 구현자 또는 검토자가 시도하기 전에, Ralph는 해당 시도의 구성을 stderr에 작성합니다. 첫 번째 줄은 스테이지 배너 바로 다음에 나타납니다:

== iteration 2/5 · reviewer (stage 2/2) ==
attempt 1 · codex · configured model=gpt-6-sol (Ralph default) · effort=high (Ralph default)

재시도는 또 다른 줄(attempt 2 등)을 출력하며, 스테이지마다 번호 매기기가 1부터 다시 시작됩니다. 이 줄은 템플릿 렌더링 전에 방출되므로, 시도를 소모하는 렌더 실패도 여전히 표시됩니다. 게이트가 HEAD를 이동시키지 않아 건너뛴 스테이지는 기존의 건너뛰기 메시지를 유지하고 시도 구성은 출력하지 않습니다. 이 줄이 stderr로 가기 때문에 --detach 로그에도 포착됩니다. 항상 일반 텍스트(TTY에서도 ANSI 없음)이며, 제어 문자는 표시를 위해 이스케이프되어 있어 설정된 값이 다른 터미널 줄이나 이스케이프 시퀀스를 주입할 수 없습니다. 이스케이핑은 표시 전용이며 제공자에게 전달되는 값은 변경하지 않습니다.

configured는 의도적입니다: 이것은 Ralph가 요청한 값이지, 백엔드가 실제로 사용한 모델 또는 추론 모드의 증거가 아닙니다. Ralph가 스위치를 의도적으로 생략하면, 그 줄은 값을 추측하는 대신 provider-managed라고 표시됩니다. 예시로는 비조정된 Claude 노력(effort), 타사 라우팅 하의 Claude 모델 선택, 그리고 --codex-user-config로 상속받는 비조정 Codex 필드가 있습니다.

Claude의 경우 호스트 설정은 env.ANTHROPIC_MODEL로 읽히고, 그렇지 않으면 저장된 model 키 /model (그것의 '(default)' 항목은 모델을 저장하지 않습니다)가 사용됩니다. Ralph는 --model을 전달합니다.

컨테이너가 선택하도록 하는 것보다는, 샌드박스 이미지의 CLI는 이미지 빌드 시점에 고정되어 있고 내장 기본값이 호스트의 값보다 뒤처질 수 있기 때문입니다 (단계별 claude update는 CLI를 새로고침하지만, RALPH_CLAUDE_UPDATE=0 또는 오프라인 상태에서는 그렇지 않습니다 — "Troubleshooting" 참조).

예외는 타사 라우팅(third-party routing)입니다. 호스트 설정이 CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, 또는 CLAUDE_CODE_USE_FOUNDRY를 활성화하는 경우, 모델 ID는 제공업체별(provider-specific)이므로 Ralph는 --model을 보내지 않으며 컨테이너 CLI는 이전과 같이 해결됩니다. 노력(effort)은 설정될 때 여전히 전송됩니다: --effort <level>는 모델 ID가 아니라 CLI 설정입니다.

Codex는 노력(effort)을 -c model_reasoning_effort="<level>"로 전송합니다. Isolated Codex는 모델이 지정되더라도 Ralph의 high 기본값을 유지합니다 — 모델 이름을 지정하는 것이 더 이상 노력을 Codex CLI 자체에 자동으로 낮추지 않습니다 (동작 변경; "Troubleshooting" 참조). --codex-user-config를 사용하면 플래그나 변수가 덮어쓰지 않는 한 파일이 둘 다 제공합니다. 명시적으로 유효하지 않은 모델이나 호환되지 않는 노력은 Codex에서 실패하며, Ralph는 다른 모델이나 낮은 노력으로 절대 재시도하지 않습니다.

노력 수준(Effort levels)은 에이전트별로 허용 목록(allowlisted)에 있습니다: Claude는 low|medium|high|xhigh|max를 사용하며, unattended stage가 워크플로우 오케스트레이션(workflow orchestration)을 시작할 수 없기 때문에 ultracode는 의도적으로 제외되었습니다 — 그리고 Codex는 none, minimal, 및 ultra를 추가합니다. RALPH_EFFORT는 에이전트와 무관하므로, 모든 에이전트가 받아들이는 수준만(현재 low|medium|high|xhigh|max) 허용하며; ultra와 같은 제공업체 전용 수준은 RALPH_CODEX_EFFORT에 들어갑니다. 알 수 없는 수준은 컨테이너가 시작되기 전에 실행을 종료시키며, 이벤트 로그에는 run.ended reason: "error"가 기록되고 1로 종료됩니다.

--print-config는 어느 경우에도 실패하지 않습니다: invalid: allowed … 접미사를 붙여 수준을 출력합니다. Ultra는 모델-, 클라이언트-, 계정 종속적입니다. Ralph가 모드를 선택하지만, 허용 목록 수락이나 --print-config를 다루지는 않습니다.

선택된 모델이 해당 기능을 실행할 자격이 있음을 증명하는 출력물입니다. Codex 0.156.1 번들 카탈로그는 이 스냅샷을 2026-09-23에 보고했습니다:

이 표는 정보 제공용이며, 영구적인 등록부나 접근 보증이 아닙니다. 최신 클라이언트는 이를 변경할 수 있으며, 사용자 지정 또는 오래된 이미지는 더 새로운 Codex 버전이 필요할 수 있습니다. Ralph는 이 현대 모델 스냅샷에서 해당 값이 누락되었음에도 불구하고 호환되는 모델에 대해 여전히 none 및 minimal을 허용합니다. 현재의 호환성 오류는 Codex가 소유하고 있습니다.