Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Ralph는 Claude Code 기술을 구현한 자율 AI 개발 루프 도구입니다. 이 도구는 무한 루프와 API 과사용을 방지하는 안전 장치를 갖추고, 프로젝트가 완료될 때까지 코드를 반복적으로 개선합니다. 세션 연속성 확보 및 속도 제한 기능으로 안정적이고 체계적인 개발 환경을 제공합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Claude Ecosystem의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기CI
License: MIT
Version
Tests
GitHub Issues
Mentioned in Awesome Claude Code
Follow on X
지능형 종료 감지 및 속도 제한(rate limiting)을 갖춘 자율 AI 개발 루프
Ralph는 Geoffrey Huntley의 Claude Code 기술을 구현한 것으로, 그가 Ralph Wiggum의 이름을 따서 명명한 연속적인 자율 개발 사이클을 가능하게 합니다. 이 도구는 Claude Code가 무한 루프와 API 과사용(API overuse)을 방지하는 내장 안전 장치와 함께 프로젝트를 완료될 때까지 반복적으로 개선할 수 있도록 하는 연속적인 자율 개발 사이클을 구현합니다.
한 번 설치하면 어디서든 사용 가능 - Ralph는 모든 디렉터리에서 사용할 수 있는 전역 명령(global command)이 됩니다.
버전(Version): v0.11.5 - 활성 개발 (Active Development)
핵심 기능(Core Features): 작동 및 테스트 완료 (Working and tested)
테스트 커버리지(Test Coverage): 784개 테스트, 100% 통과율 (pass rate)
EXIT_SIGNAL 두 가지 모두 필요--resume 플래그를 사용한 세션 연속성 확보(세션 하이재킹 방지)--output-format, --allowed-tools, --no-continueralph-enable 위저드를 사용한 대화형 프로젝트 활성화 기능.ralphrc 설정 파일--live 플래그를 이용한 라이브 스트리밍 출력ralph.log는 10MB 단위로 순환하며 4개의 아카이브 파일 유지--dry-run)ralph-stats 분석 명령을 이용한 메트릭 추적 (루프당 JSON Lines 형식의 메트릭)--notify) (macOS/Linux/터미널 벨)--backup 및 --rollback 복원 기능을 갖춘 자동 Git 백업 브랜치ralph-import --github-issue 및 메타데이터 필터(레이블, 제목, 담당자, 마일스톤, 상태)를 이용하며, 첫 번째/대화형/우선순위 선택과 --dry-run 미리보기를 지원미출시 - 보안: .ralphrc가 데이터로 파싱됨 (#346)
.ralphrc는 더 이상 source로 실행되지 않습니다: 알려진 키에 대한 KEY=VALUE 라인만 리터럴 값으로 적용됩니다. 셸 구문 ($VAR, $(...), 연결된 명령어)은 경고와 함께 거부되며, 이는 해당 기능에 의존했던 .ralphrc 파일에는 **호환성 문제(breaking)**를 일으킵니다.CLAUDE_CODE_CMD, RALPH_SHELL_INIT_FILE, SANDBOX_DOCKER_IMAGE, SANDBOX_E2B_TEMPLATE 및 SANDBOX_DOCKER_NETWORK (host 없음)는 .ralphrc에서 제공하는 기본 값만 허용합니다. 사용자 정의 값은 환경 변수(또는 --sandbox-* 플래그)로 설정해야 합니다. 이는 ralph, ralph-import, 및 ralph-queue에 적용됩니다. docs/CLI_OPTIONS.md를 참조하십시오.v0.11.5 - 커뮤니티 버그 수정 (최신)
rate_limit_event) → 필터링된 텍스트 폴백(fallback).${,,} 소문자 치환이 POSIX tr로 대체되었습니다 (#187).⚠️ [IMG:N]
v0.11.4 - 버그 수정 및 호환성
[2026-01-29]은 더 이상 체크박스로 계산되지 않습니다 (#144)--continue 대신 --resume <세션_ID>를 사용해야 합니다 (#151)STATUS: COMPLETE와 EXIT_SIGNAL: false가 이제 계속 작동합니다 (#146)--print 플래그 추가)base-index 설정을 위한 tmux 지원 추가v0.11.3 - 라이브 스트리밍 및 Beads 수정
--live 플래그를 사용하여 실시간 Claude Code 가시성을 위한 라이브 스트리밍 출력 모드 추가 (#125)bd list 인수를 사용한 beads 작업 가져오기(import) 기능 수정 (#150)v0.11.2 - 설정 권한 수정
ralph-setup이 일관된 도구 권한으로 .ralphrc를 생성하도록 수정ALLOWED_TOOLS 업데이트: Edit, Bash(npm *), 그리고 Bash(pytest) 포함ralph-setup과 ralph-enable 모두 동일한 .ralphrc 구성을 생성합니다v0.11.1 - 완료 표시기 수정
completion_indicators는 이제 EXIT_SIGNAL: true일 때만 누적됩니다v0.11.0 - Ralph Enable Wizard
ralph-enable 대화형 위자드(interactive wizard) 추가ralph-enable-ci 추가enable_core.sh, wizard_utils.sh, task_sources.shv0.10.1 - 버그 수정 및 모니터 경로 수정 (Bug Fixes & Monitor Path Corrections)
ralph_monitor.sh의 하드코딩된 경로 수정v0.10.0 - .ralph/ 하위 폴더 구조 (BREAKING CHANGE)
.ralph/ 하위 폴더로 이동src/, README.md, 사용자 파일만 남음ralph-migrate 명령어 추가v0.9.9 - EXIT_SIGNAL 게이트 및 제거 스크립트 (EXIT_SIGNAL Gate & Uninstall Script)
EXIT_SIGNAL: true가 필요하도록 변경uninstall.sh 스크립트 추가v0.9.8 - PRD 가져오기를 위한 최신 CLI (Modern CLI for PRD Import)
ralph_import.sh를 Claude Code CLI JSON 출력 형식을 사용하도록 현대화v0.9.7 - 세션 수명 주기 관리 (Session Lifecycle Management)
--reset-session CLI 플래그 추가v0.9.6 - JSON 출력 및 세션 관리 (JSON Output & Session Management)
parse_json_response() 확장v0.9.5 - v0.9.0 - PRD 가져오기 테스트(PRD import tests), 프로젝트 설정 테스트(project setup tests), 설치 테스트(installation tests), 프롬프트 파일 수정(prompt file fix), 최신 CLI 명령어 추가(modern CLI commands), 회로 차단기 개선 사항(circuit breaker enhancements)
claude로부터 분리하여, 어떤 헤드리스 코딩 CLI(Codex, Gemini, OpenCode, Droid, Kilocode, Copilot 등)라도 루프를 구동할 수 있도록 합니다(multi-provider 에픽; 에이전트 어댑터 계약도 참조).v1.0까지의 로드맵: 최종 다듬기 작업 진행 중 | 전체 로드맵 | 기여 환영! (Contributions welcome!)
자율 개발 루프 (Autonomous Development Loop) - 프로젝트 요구사항에 따라 Claude Code를 지속적으로 실행합니다.
지능형 종료 감지 (Intelligent Exit Detection) - 완료 지표(completion indicators)와 명시적인 EXIT_SIGNAL 두 가지 조건을 모두 확인해야 합니다.
세션 연속성 (Session Continuity) - 자동 세션 관리 기능을 통해 루프 반복 간 컨텍스트를 보존합니다.
세션 만료 (Session Expiration) - 설정 가능한 타임아웃(기본값: 24시간)과 자동 세션 재설정 기능이 있습니다.
속도 제한 처리 (Rate Limiting) - 시간당 제한 및 카운트다운 타이머가 포함된 내장 API 호출 관리 기능을 제공합니다.
5시간 API 제한 처리 (5-Hour API Limit Handling) - 비감독 모드(unattended mode)를 위해 타임아웃 가드, JSON 파싱, 필터링된 텍스트의 세 가지 계층적 감지 및 자동 대기 기능이 있습니다.
실시간 모니터링 (Live Monitoring) - 루프 상태, 진행 상황 및 로그를 보여주는 실시간 대시보드를 제공합니다.
작업 관리 (Task Management) - 우선순위가 지정된 작업 목록과 진행 상황 추적을 통해 구조화된 접근 방식을 제공합니다.
프로젝트 템플릿 (Project Templates) - 모범 사례 구조를 갖춘 새 프로젝트의 빠른 설정을 지원합니다.
대화형 프로젝트 설정 (Interactive Project Setup) - 기존 프로젝트에 대한 작업 가져오기(task import) 기능을 가진 ralph-enable 마법사(wizard)를 제공합니다.
설정 파일 (Configuration Files) - 프로젝트별 설정 및 도구 권한을 위한 .ralphrc 파일을 사용합니다.
종합 로깅 (Comprehensive Logging) - 타임스탬프와 상태 추적 기능이 포함된 상세 실행 로그를 제공합니다.
설정 가능한 타임아웃(Configurable Timeouts) - Claude Code 작업에 대한 실행 시간 제한 설정 (1~120분)
상세 진행 모드(Verbose Progress Mode) - 실행 중 선택적 상세 진행 업데이트
응답 분석기(Response Analyzer) - 의미론적 이해를 갖춘 AI 기반의 Claude Code 응답 분석
회로 차단기(Circuit Breaker) - 2단계 필터링, 다중 라인 오류 매칭 및 자동 복구 기능을 갖춘 고급 오류 감지
CI/CD 통합(Integration) - 자동화된 테스트가 포함된 GitHub Actions 워크플로우
깔끔한 제거(Clean Uninstall) - 완전한 제거를 위한 전용 제거 스크립트
실시간 스트리밍 출력(Live Streaming Output) - --live 플래그를 사용한 Claude Code 실행의 실시간 가시성 확보
Docker 샌드박스 실행(Docker Sandbox Execution) - --sandbox docker를 사용하여 격리된 컨테이너에서 Claude Code 실행 (리소스 제한, 네트워크 정책, 안전한 자격 증명 전달)
E2B 클라우드 샌드박스 실행(E2B Cloud Sandbox Execution) - --sandbox e2b를 사용하여 E2B 클라우드 샌드박스에서 Claude Code 실행 (파일 동기화, 세션 복구, --sandbox-max-cost를 사용한 비용 추적)
Ralph는 두 가지 단계로 구성됩니다: **일회성 설치(one-time installation)**와 프로젝트별 설정(per-project setup).
INSTALL ONCE USE MANY TIMES
+-----------------+ +----------------+++
| ./install.sh | -> | ralph-setup project1 |
...
시스템에 전역적으로 Ralph를 설치합니다:
git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
./install.sh
이 명령어는 ralph, ralph-monitor, ralph-setup, ralph-import, ralph-queue, ralph-migrate, ralph-enable, 그리고 ralph-enable-ci 명령어를 PATH에 추가합니다.
참고: 이 작업은 시스템당 한 번만 수행하면 됩니다. 설치 후 원한다면 클론된 저장소를 삭제해도 무방합니다.
cd my-existing-project
# 대화형 마법사 - 프로젝트 유형을 자동 감지하고 작업을 가져옵니다.
...
# 기존 PRD/사양을 Ralph 형식으로 변환
ralph-import my-requirements.md my-project
cd my-project
...
# 빈 Ralph 프로젝트 생성
ralph-setup my-awesome-project
cd my-awesome-project
...
Ralph이 설치되고 프로젝트가 초기화되면: