iannuttall/ralph

Ralph는 자율 코딩 (autonomous coding)을 위한 최소한의 파일 기반 에이전트 루프 (agent loop)입니다. 각 반복 (iteration)은 새롭게 시작되며, 동일한 디스크 상의 상태 (on-disk state)를 읽고, 한 번에 하나의 스토리 (story)에 대한 작업을 커밋 (commit)합니다.

Ralph는 모델 컨텍스트 (model context)가 아닌 파일과 git을 메모리 (memory)로 취급합니다:

**PRD (JSON)**는 스토리 (stories), 게이트 (gates), 상태 (status)를 정의합니다
**루프 (Loop)**는 반복당 하나의 스토리를 실행합니다
**상태 (State)**는 .ralph/에 영구적으로 저장됩니다

어디에서나 Ralph를 설치하고 실행하세요:

npm i -g @iannuttall/ralph
ralph prd # 대화형 프롬프트 (interactive prompt)를 실행합니다
ralph build 1 # 한 번의 Ralph 실행

Ralph는 다음 순서로 템플릿 (templates)을 찾습니다:

.agents/ralph/

현재 프로젝트 내에 있는 경우 - 이 리포지토리 (repo)와 함께 제공되는 번들 기본값 (Bundled defaults)

상태 (State)와 로그 (logs)는 항상 프로젝트의 .ralph/로 이동합니다.

ralph install

이 명령은 현재 리포지토리 (repo)에 .agents/ralph/를 생성하여 프롬프트 (prompts)와 루프 동작 (loop behavior)을 사용자 정의 (customize)할 수 있게 합니다. 설치 중에 필요한 스킬 (skills)을 추가할지 여부를 묻습니다.

ralph install --skills

에이전트 (agent) (codex/claude/droid/opencode) 및 로컬 (local) 대 글로벌 (global) 설치 여부를 묻는 프롬프트가 나타납니다. 설치되는 스킬 (skills): commit, dev-browser, prd.
ralph install 중에 스킬 (skills)을 건너뛰었다면, 언제든지 ralph install --skills를 실행할 수 있습니다.

• PRD (JSON)를 생성하거나 직접 작성하세요:

ralph prd

prd 스킬이 필요합니다 (ralph install --skills를 통해 설치).

프롬프트 텍스트 예시:

A lightweight uptime monitor (Hono app), deployed on Cloudflare, with email alerts via AWS SES

기본 출력 (에이전트가 .agents/tasks/ 내에서 짧은 파일 이름을 선택함):

.agents/tasks/prd-<short>.json

• 한 번의 빌드 반복 (build iteration)을 실행하세요:

ralph build 1 # 한 번의 Ralph 실행

커밋하지 않는 드라이 런 (dry run):

ralph build 1 --no-commit # 한 번의 Ralph 실행

ralph prd의 PRD 출력을 재정의 (override) 하려면:

ralph prd --out .agents/tasks/prd-api.json

선택 사항인 인간용 개요 (human overview) (JSON에서 생성됨):

ralph overview

이 명령은 PRD와 함께 작은 개요를 작성합니다: prd-<slug>.overview.md.

PRD 스토리 상태 (story status) 필드는 루프 (loop)에 의해 자동으로 업데이트됩니다:

open
→ 선택 가능한 in_progress

→ 실행 중인 루프에 의해 잠김 (startedAt 포함)

done

→ 완료됨 (completedAt 포함)

만약 루프가 충돌하여 스토리 (story)가 in_progress 상태로 남아 있는 경우, .agents/ralph/config.sh에서 STALE_SECONDS를 설정하여 Ralph가 중단된 스토리를 자동으로 다시 열 수 있도록 할 수 있습니다.

CLI 플래그를 통해 Ralph가 다른 PRD JSON 파일을 참조하도록 지정할 수 있습니다:

ralph build 1 --prd .agents/tasks/prd-api.json # 한 번의 Ralph 실행

선택적 진행 상황 재정의 (Optional progress override):

ralph build 1 --progress .ralph/progress-api.md # 한 번의 Ralph 실행

.agents/tasks/에 여러 개의 PRD JSON 파일이 존재하고 --prd를 생략하면, Ralph가 선택을 요청합니다.

선택적 설정 파일 (템플릿을 설치한 경우):

.agents/ralph/config.sh

에이전트 (agent)를 전환하려면 .agents/ralph/config.sh에서 AGENT_CMD를 설정하세요:

AGENT_CMD="codex exec --yolo -"
AGENT_CMD="claude -p --dangerously-skip-permissions \"\$(cat {prompt})\""
AGENT_CMD="droid exec --skip-permissions-unsafe -f {prompt}"
...

또는 실행 시마다 재정의할 수 있습니다:

ralph prd --agent=codex
ralph build 1 --agent=codex # 한 번의 Ralph 실행
ralph build 1 --agent=claude # 한 번의 Ralph 실행
...

CLI가 설치되어 있지 않으면 Ralph가 설치 힌트를 출력합니다:

codex -> npm i -g @openai/codex
claude -> curl -fsSL https://claude.ai/install.sh | bash
droid -> curl -fsSL https://app.factory.ai/cli | sh
...

progress.md — 추가 전용 (append-only) 진행 로그
guardrails.md — "Signs" (학습된 교훈)
activity.log — 활동 + 타이밍 로그
errors.log — 반복된 실패 및 노트
runs/ — 원시 실행 로그 + 요약

.agents/ralph는 이식 가능하며 리포지토리 (repo) 간에 복사할 수 있습니다.
.ralph는 프로젝트별 상태 (per-project state)입니다.

• 에이전트가 표준 입력 (stdin) 대신 파일 경로가 필요한 경우 AGENT_CMD에서 {prompt}를 사용하세요. - 예시: examples/commands.md 참조.

• OpenCode 서버 모드: OpenCode를 사용하여 더 빠른 성능을 내려면, 별도의 터미널에서 opencode serve를 실행하고 .agents/ralph/agents.sh에서 AGENT_OPENCODE_CMD 라인의 주석을 해제하여 --attach http://localhost:4096을 사용하세요. 이렇게 하면 매 실행 시마다 발생하는 콜드 부트 (cold boot)를 방지할 수 있습니다.

드라이 런 (Dry-run) 스모크 테스트 (에이전트 불필요):

npm test

빠른 에이전트 상태 확인 (실제 에이전트 호출, 최소한의 출력):

npm run test:ping

선택적 통합 테스트 (에이전트 설치 필요):

RALPH_INTEGRATION=1 npm test

전체 실제 에이전트 루프 테스트:

npm run test:real