manager / planner / developer / qa 자율 에이전트 루프 CLI
ralph 루프는 내부적으로 codex exec를 사용합니다.
codex --version
codex login status로그인이 안 되어 있으면:
codex loginAPI 키 로그인:
printenv OPENAI_API_KEY | codex login --with-api-keymacOS / Ubuntu:
curl -fsSL https://raw.githubusercontent.com/emperorhan/codex-ralph/main/scripts/install-ralphctl.sh | bash설치 확인:
ralphctl --help- 기본 control dir:
~/.ralph-control - 첫 실행 시 필요한 기본 plugin/registry가 자동 준비됩니다.
프로젝트 루트에서:
ralphctl --project-dir "$PWD" bootstrap이후:
./ralph실행 헬퍼가 생성됩니다.- 로컬 Git 저장소가 없으면 자동 초기화됩니다.
- 기본 설정 파일:
.ralph/profile.yaml.ralph/profile.local.yaml
- 안정성 기본값(timeout/retry/watchdog/primary daemon restart)이 적용됩니다.
- 완료(
done)된 이슈 단위로 자동 커밋이 누적됩니다(임시/런타임 파일 제외). - canonical runtime은
Ralph Runtime(.ralph-runtime) 입니다.
ralphctl --project-dir "$PWD" doctor
ralphctl --project-dir "$PWD" status
ralphctl --project-dir "$PWD" work
ralphctl --project-dir "$PWD" eval문제가 있으면:
ralphctl --project-dir "$PWD" doctor --repair
ralphctl --project-dir "$PWD" cp recover
ralphctl --project-dir "$PWD" retry-blocked --reason codex_failed_afterpublic 사용자는 아래 happy path를 기준으로 시작하면 됩니다.
ralphctl --project-dir "$PWD" bootstrap
ralphctl --project-dir "$PWD" intake "헬스체크 엔드포인트 추가하고 테스트까지 마무리해줘"
ralphctl --project-dir "$PWD" intake status
ralphctl --project-dir "$PWD" intake revise "반드시 끝나야 하는 결과는 /health 엔드포인트와 관련 테스트 통과입니다."
ralphctl --project-dir "$PWD" intake status
ralphctl --project-dir "$PWD" intake approve
ralphctl --project-dir "$PWD" status지원 환경:
- macOS / Linux
- 로컬 Git 프로젝트
codex exec사용 가능 환경
참고 문서:
- public-launch-readiness.md
- public-known-limitations.md
- public-release-notes-template.md
- public-ship-audit.md
- fresh-machine-smoke-runbook.md
- telegram-public-smoke-runbook.md
- public-troubleshooting.md
- public-release-checklist.md
bash scripts/run-public-release-gate.sh "$PWD"bash scripts/collect-fresh-machine-smoke-record.shbash scripts/collect-telegram-smoke-record.sh
수동 이슈 생성:
ralphctl --project-dir "$PWD" intake issue developer "health endpoint 구현"
ralphctl --project-dir "$PWD" intake issue --priority 10 --story-id US-001 developer "결제 API 에러 처리 개선"PRD JSON 일괄 생성:
ralphctl --project-dir "$PWD" intake prd --file prd.json --default-role developer자연어 요청에서 이슈 생성:
ralphctl --project-dir "$PWD" intake request "결제 API 에러 처리를 정리하고 테스트까지 추가해줘"
ralphctl --project-dir "$PWD" intake "헬스체크 엔드포인트 추가하고 문서도 업데이트해줘"intent session 점검/승인:
ralphctl --project-dir "$PWD" intake status
ralphctl --project-dir "$PWD" intake brief
ralphctl --project-dir "$PWD" intake approve
ralphctl --project-dir "$PWD" intake revise "성공 기준은 smoke test 통과"
ralphctl --project-dir "$PWD" intake abortintake approve 이후에는 workload별 auto-run 정책이 적용됩니다. 기본값에서는 terminal verify 전까지만 자동 실행하고, status와 Telegram /task status는 summary / situation / next_action 형식의 operator cockpit 문구로 현재 경계와 재개 포인트를 보여줍니다. public-safe 기본값을 벗어나면 public_guardrail 경고와 emergency_action 안내가 같이 출력됩니다.
이전 ./ralph start, ./ralph run, ralphctl supervise 기반 loop 경로는 제거되었습니다. 현재 권장 실행 경로는 Ralph Runtime + session orchestration 입니다.
ralphctl --project-dir "$PWD" work
ralphctl --project-dir "$PWD" status
ralphctl --project-dir "$PWD" eval
ralphctl --project-dir "$PWD" cp doctor --repair --strict대부분의 사용자는 bootstrap, intake, work, status, eval, doctor만 쓰면 됩니다. cp는 low-level control-plane ops/debug namespace로 남겨둔 advanced 명령군입니다.
주요 산출물:
.ralph/done/: 완료 이슈.ralph/blocked/: 실패/검토 필요 이슈.ralph/logs/: 실행 로그
legacy blocked 이슈 재시도:
ralphctl --project-dir "$PWD" retry-blocked
ralphctl --project-dir "$PWD" retry-blocked --reason codex_failed_after
ralphctl --project-dir "$PWD" retry-blocked --reason codex_permission_denied --limit 1이 섹션은 운영/디버깅이 필요한 경우에만 직접 쓰는 advanced cp 명령들입니다.
ralphctl --project-dir "$PWD" cp init
ralphctl --project-dir "$PWD" cp import-intent --file intent.json
ralphctl --project-dir "$PWD" cp plan --intent-id <intent-id># 기본 실행 (verify 중심)
ralphctl --project-dir "$PWD" cp run --max-workers 1
# Codex 실행 + verify
ralphctl --project-dir "$PWD" cp run --max-workers 1 --execute-with-codex
# blocked 복구 (policy 존중: retry budget/backoff/circuit)
ralphctl --project-dir "$PWD" cp recover
# 즉시 강제 복구 (cooldown/circuit 우회)
ralphctl --project-dir "$PWD" cp recover --force
ralphctl --project-dir "$PWD" cp status --json
ralphctl --project-dir "$PWD" cp metrics --json
ralphctl --project-dir "$PWD" cp metrics --with-baseline --json
ralphctl --project-dir "$PWD" cp doctor --repair --repair-recover-limit 10 --strict
# cooldown/circuit 우회가 필요할 때
ralphctl --project-dir "$PWD" cp doctor --repair --repair-force-recover --strict
# blocked circuit/재시도 예산을 수동 초기화할 때
ralphctl --project-dir "$PWD" cp doctor --repair --repair-reset-circuit --repair-reset-retry-budget --strict
# fault injection (신뢰성 테스트)
ralphctl --project-dir "$PWD" cp fault-inject --task-id task-1 --mode lease-expire
ralphctl --project-dir "$PWD" cp fault-inject --task-id task-1 --mode verify-fail
ralphctl --project-dir "$PWD" cp fault-inject --task-id task-1 --mode execute-fail
ralphctl --project-dir "$PWD" cp fault-inject --task-id task-1 --mode permission-deniedadvanced cp doctor 핵심 data integrity 체크:
task_json_consistencyevent_journal_consistencylearning_journal_consistencyevent_ledger_consistencylearning_ledger_consistency
검증 정책 엔진(unit|integration|lint|custom) 사용 예시:
{
"verify_cmd": "lint: golangci-lint run\nunit: go test ./...\ncustom: ./scripts/verify_extra.sh"
}접두어가 없으면 custom으로 처리됩니다.
readiness eval은 Ralph Runtime + session harness의 병합 가능성을 점수표와 시나리오 결과로 확인하는 명령입니다.
ralphctl --project-dir "$PWD" eval실행하면 텍스트 요약과 함께 아래 아티팩트가 생성됩니다.
.ralph-runtime/reports/eval/latest.json.ralph-runtime/reports/eval/latest.md.ralph-runtime/reports/eval/runs/<timestamp>/scorecard.json.ralph-runtime/reports/eval/runs/<timestamp>/scenarios.json.ralph-runtime/reports/eval/runs/<timestamp>/summary.md
출력에는 ready, hard_gate_passed, soft_gate_passed, total_score와 시나리오별 pass/fail 요약이 포함됩니다.
Ready: hard gate를 통과했고 총점 기준도 충족한 상태Not Ready: hard gate가 하나라도 실패한 상태hard gate: task execution, memory safety, operational resilience 같은 필수 축의 최소 통과 조건soft gate: 병합은 가능하지만 후속 개선이 필요한 보조 조건
intent eval은 최신 intent session과 execution brief의 명확도를 빠르게 점검하는 명령입니다.
ralphctl --project-dir "$PWD" cp intent-eval실행하면 아래 아티팩트가 생성됩니다.
.ralph-runtime/reports/intent-eval/latest.json.ralph-runtime/reports/intent-eval/latest.md.ralph-runtime/reports/intent-eval/runs/<timestamp>/report.json.ralph-runtime/reports/intent-eval/runs/<timestamp>/summary.md
competitive eval은 internal benchmark/experiment surface입니다. 일반 사용자 기능이 아니라, 하네스 품질과 operator 경험을 내부적으로 비교 점검하기 위한 평가 표면입니다.
ralphctl --project-dir "$PWD" cp competitive-evalbaseline mode는 현재처럼 codex-ralph를 직접 실행해 점수화합니다.
ralphctl --project-dir "$PWD" cp competitive-evalmanual adapter path는 외부 하네스를 직접 실행하는 기능이 아니라, internal benchmark 실험을 위한 guide/evidence 표면입니다.
bundle emit:
ralphctl --project-dir "$PWD" cp competitive-eval \
--emit-manual-bundle \
--harness <internal-benchmark-harness> \
--scenario <scenario>manual parse:
ralphctl --project-dir "$PWD" cp competitive-eval \
--parse-manual-bundle .ralph-runtime/reports/competitive-eval/manual-bundles/<internal-benchmark-harness>/<scenario>실행하면 아래 아티팩트가 생성됩니다.
.ralph-runtime/reports/competitive-eval/latest.json.ralph-runtime/reports/competitive-eval/latest.md.ralph-runtime/reports/competitive-eval/runs/<timestamp>/result.json.ralph-runtime/reports/competitive-eval/runs/<timestamp>/summary.md.ralph-runtime/reports/competitive-eval/manual-bundles/<harness>/<scenario>/scenario.json.ralph-runtime/reports/competitive-eval/manual-bundles/<harness>/<scenario>/instructions.md.ralph-runtime/reports/competitive-eval/manual-bundles/<harness>/<scenario>/evidence-template.json
manual bundle과 parse 경로는 internal benchmark harness를 상정하며, 일반 제품 기능으로 문서화하지 않습니다.
현재 semantics는 다음과 같습니다.
- baseline mode
run_mode=baselineharness_kind=command-driven
- manual parse mode
run_mode=manual-parseharness_kind=manual
- manual interpreted mode
run_mode=manual-parsemeasurement_mode=manual-interpreted- harness-specific parser가 competitor 결과를 해석한 상태
manual parse는 generic parser 단계에서는 competitor 성공/실패를 최종 판정하지 않고, evidence bundle을 neutral provenance로 정리합니다. 이후 harness-specific parser/adapter가 붙으면 같은 report 파이프라인 안에서 scorecard 해석을 더 정교하게 올릴 수 있습니다.
1차 scenario pack:
one_line_featureblocked_then_resumetelegram_control_roundtripintegration_boundary_change
operator playbook:
- pre-run
- clean workspace 확인
- 같은 scenario contract와 success 기준 확인
- during-run
- clarification, blocked, remote control 개입 지점을
notes.txt에 기록 - competitor-specific deviation이 있으면 함께 남김
- clarification, blocked, remote control 개입 지점을
- post-run
stdout.log,stderr.log,notes.txt정리- 가능하면
summary.json에timing,operator_count를 함께 남김 - listed artifact를 bundle에 같이 보관
evidence discipline:
- 필수
notes.txt- transcript에 준하는 text evidence
- 권장
summary.json- harness-specific artifact
- 원칙
- generic parser는 evidence를 neutral provenance로만 읽음
- scorecard interpretation은 harness-specific parser가 붙을 때 올림
intent-driven autonomous loop의 완성도는 아래 targeted regression 묶음으로 점검합니다.
env GOCACHE=/tmp/ralph-gocache CGO_ENABLED=0 go test ./internal/ralph -run 'Test(Intent(FeatureFlowAutoRunsUntilValidateBoundary|IntegrationFlowAutoRunsUntilFinalVerifyBoundary|OpsFlowAutoRunsUntilHealthVerifyBoundary)|RunCompetitiveEvalBaselineProducesStableMetrics|WriteCompetitiveEvalReportsWritesLatestAndTimestampedRuns)' -count=1
env GOCACHE=/tmp/ralph-gocache CGO_ENABLED=0 go test ./cmd/ralphctl -run 'Test(TelegramBlocked(ReplyRefreshesGraphAndAutoRuns|SummaryExplainsResumePoint)|RunControlPlaneCompetitiveEval(ShowsBaselineSummary|JSONMatchesReport)|PrintIntakeSessionStatusShowsCockpitSummary|TelegramTaskStatusIncludesCockpitNarrative)' -count=1위 두 명령은 다음을 함께 검증합니다.
- workload별 autonomous halt semantics
- Telegram blocked -> reply -> refreshed graph -> auto-run resume
- competitive baseline metrics/report consistency
- operator cockpit summary와 CLI/Telegram surface
advanced cp run --execute-with-codex는 이제 단순한 one-shot codex exec 호출이 아니라, Ralph Runtime 위에 얹힌 session harness를 통해 실행됩니다.
핵심 구조:
control plane: lease, heartbeat, recover, metrics, retry budgetagent harness: coordinator-owned worker session orchestrationworker session: 같은 task에 대해 start/continue turn을 가질 수 있는 실행 단위verification: worker 완료 선언과 분리된 독립 검증 단계
현재 continuity는 persistent transport가 아니라 codex exec replay 방식으로 유지됩니다.
- 외부 계약은 sessionful
- 내부 transport는 여전히
codex exec - turn continuity는
TaskMemory재구성으로 유지 - raw transcript 전체를 재주입하지 않음
--execute-with-codex 경로는 장기 실행에서 drift를 줄이기 위해 메모리를 분리합니다.
TaskMemory: 현재 task의 canonical memoryaccepted_factsopen_questionsartifactsnext_ask
ExecutionJournal: recover/audit용 실행 기록ProjectMemory:.ralph/project-memory/MEMORY.md+ topic filesUserMemory:.ralph/user-memory/MEMORY.md+ topic files
원칙:
- memory는 truth store가 아니라 skeptical hint layer입니다.
- coordinator가 승인한 사실만
TaskMemory와 장기 memory로 승격합니다. - raw transcript는 장기 memory로 복제하지 않습니다.
ExecutionJournal은 prompt 기본 payload가 아니라 필요 시 조회용입니다.
현재 harness는 coordinator-owned continuation 모델을 따릅니다.
- coordinator만 같은 worker session에 후속 메시지를 보냅니다.
- worker 결과는 structured result로 수집됩니다.
- structured result는 기존 handoff schema로 bridge 됩니다.
- handoff validator와 role-specific schema는 유지됩니다.
즉, manager/planner/developer/qa 역할 체계는 그대로 유지하면서도, 실제 Codex 실행은 session -> continuation -> verify 흐름으로 운영됩니다.
이번 단계의 명시적 비목표:
- persistent Codex session transport 도입
- 기존 loop 경로 재도입
- long-term memory를 SQLite로 이전
execute_cmd전용 task 경로 재작성
ralphctl --project-dir "$PWD" eval
ralphctl --project-dir "$PWD" cp intent-eval
ralphctl --project-dir "$PWD" cp competitive-eval
ralphctl --project-dir "$PWD" cp doctor --repair주요 산출물은 .ralph-runtime/reports/ 아래에 저장됩니다.
.ralph-runtime/reports/eval/latest.json.ralph-runtime/reports/eval/latest.md.ralph-runtime/reports/competitive-eval/latest.json.ralph-runtime/reports/competitive-eval/latest.md.ralph-runtime/autonomous-depth/
레거시 dual-runtime helper script는 제거되었습니다. Runtime 운영은 bootstrap, intake, work, status, eval, doctor 중심으로 진행합니다.
참고:
- ledger(
cp_event_ledger,cp_learning_ledger)가 비어 있고 기존cp_events/cp_learnings데이터가 있으면, 스키마 보장 단계에서 자동 backfill 됩니다.
상태 조회 API 서버:
ralphctl --project-dir "$PWD" cp api --listen 127.0.0.1:8787
curl -s http://127.0.0.1:8787/health
curl -s http://127.0.0.1:8787/runtime/status
curl -s http://127.0.0.1:8787/runtime/metrics
curl -s "http://127.0.0.1:8787/runtime/metrics?with_baseline=true"
curl -s http://127.0.0.1:8787/runtime/metrics/summary
curl -s http://127.0.0.1:8787/runtime/doctor
curl -s "http://127.0.0.1:8787/runtime/events?limit=50"
curl -N http://127.0.0.1:8787/runtime/events/stream서비스 등록(systemd/launchd):
ralphctl --project-dir "$PWD" service install --start
ralphctl --project-dir "$PWD" service status
ralphctl --project-dir "$PWD" service uninstall대화형(권장):
ralphctl fleet명령형 예시:
ralphctl fleet register --id wallet --project-dir <wallet-project-dir> --plugin universal-default --prd PRD.md
ralphctl fleet start --all
ralphctl fleet status --all
ralphctl fleet stop --all텔레그램은 필수 설정이 아닙니다.
필요한 값:
bot tokenchat-idsuser-ids(특히 그룹 제어 시 권장/필수)
값 수집 방법 (웹):
@BotFather에서 봇 생성 후 토큰 발급 (/newbot).- 봇을 사용할 대화방에 추가하고 메시지 1개 전송.
- 브라우저에서 아래 URL 열기:
https://api.telegram.org/bot<bot-token>/getUpdatesJSON에서 다음 값을 복사:
message.chat.id->chat-idsmessage.from.id->user-ids- 그룹/슈퍼그룹
chat.id는 음수(보통-100...) - 결과가 비어 있으면 봇/그룹에 메시지를 한 번 더 보내고 새로고침
원격 머신 세팅 시에는 로컬 브라우저에서 값을 확인한 뒤, 서버에서 아래처럼 입력하면 됩니다:
ralphctl --project-dir "$PWD" telegram setup --non-interactive \
--token "<bot-token>" \
--chat-ids "<chat-id>" \
--user-ids "<user-id>" \
--allow-control=false \
--notify=true \
--notify-scope auto \
--command-timeout-sec 300 \
--command-concurrency 4권장:
ralphctl --project-dir "$PWD" telegram setup
ralphctl --project-dir "$PWD" telegram run
ralphctl --project-dir "$PWD" telegram status
ralphctl --project-dir "$PWD" telegram tail
ralphctl --project-dir "$PWD" telegram stoptelegram run은 기본적으로 백그라운드 daemon으로 실행됩니다.- 터미널을 종료해도 계속 동작합니다.
- 포그라운드로 실행하려면
telegram run --foreground를 사용하세요.
비대화형:
ralphctl --project-dir "$PWD" telegram setup --non-interactive \
--token "<bot-token>" \
--chat-ids "<allowed-chat-id-1>,<allowed-chat-id-2>" \
--user-ids "<allowed-user-id-1>,<allowed-user-id-2>" \
--allow-control=false \
--notify=true \
--notify-scope auto \
--command-timeout-sec 300 \
--command-concurrency 4보안 규칙:
allow-control=true+ 그룹/슈퍼그룹 chat id(음수) 조합에서는user-ids가 필수입니다.- 제어 명령을 열 때는
user-ids설정을 권장합니다. - 기본 정책은
1 bot = 1 project입니다. 같은 bot token을 다른 프로젝트에서 실행하면 차단됩니다. - bot token을 다른 프로젝트로 이동하려면:
telegram run --rebind-bot - telegram offset은 프로젝트별로 자동 분리되어
~/.ralph-control/telegram-offsets/*.offset에 저장됩니다.
주요 명령:
/status [all|<project_id>]/doctor [all|<project_id>]/fleet [all|<project_id>]- 평문 메시지: 프로젝트 컨텍스트 Codex 대화 (예:
결제 PRD 초안 만들어줘) /chat <message>: Codex 대화를 명시적으로 실행/chat status,/chat reset: Codex 대화 컨텍스트 확인/초기화- (
--allow-control일 때)/start|/stop|/restart|/doctor_repair|/recover|/retry_blocked [all|<project_id>] /doctor_repair는 현재 프로젝트 기준으로repair + recover + codex blocked 재큐잉 + 필요 시 circuit reset + daemon 자동 시작까지 한 번에 수행합니다.- (
--allow-control일 때)/new [manager|planner|developer|qa] <title>(quick issue create, role 생략 시 developer) - (
--allow-control일 때)/task <자연어 요청>(canonical intake request; Codex가 role/title/objective/acceptance를 구조화해 이슈 생성) - (
--allow-control일 때)/prd help(대화형 PRD wizard + clarity refine)
PRD wizard 빠른 흐름:
/prd start/prd refine(부족한 컨텍스트를 질문으로 채움)- 스토리 입력:
title -> description -> role -> priority /prd score또는/prd preview/prd apply(점수 미달이면/prd refine유도)
대화형 입력 팁:
- refine 중에 질문형 입력(
포함 범위가 뭐야?)을 보내면 단계를 유지한 채 설명을 반환합니다. - 추천 요청(
제외 범위 추천해줘)을 보내면 현재 단계 기준 추천안을 반환합니다. - refine 입력 의도(
답변/설명/추천)는 Codex가 우선 판단합니다. /prd score,/prd apply의 게이트 점수는 Codex 점수를 우선 사용합니다(불가 시 heuristic 폴백).- PRD 세션이 활성화된 채팅에서는 평문 입력이 우선
/prd세션 입력으로 처리됩니다.
profile.local.yaml을 수정하면 실행 중인 루프가 자동으로 재로딩합니다(다음 loop부터 반영).
자주 쓰는 값:
codex_model: auto
codex_home: .codex-home
codex_exec_timeout_sec: 900
codex_retry_max_attempts: 3
codex_retry_backoff_sec: 10
codex_require_exit_signal: true
codex_exit_signal: "EXIT_SIGNAL: DONE"
codex_context_summary_enabled: true
codex_context_summary_lines: 8
codex_circuit_breaker_enabled: true
codex_circuit_breaker_failures: 3
codex_circuit_breaker_cooldown_sec: 120
idle_sleep_sec: 20
inprogress_watchdog_enabled: true
inprogress_watchdog_stale_sec: 1800
inprogress_watchdog_scan_loops: 1codex_home 기본값은 프로젝트 로컬 ./.codex-home입니다.
로그인/설정 파일(auth.json, config.toml)은 필요 시 자동 시드됩니다.
반영 확인:
./ralph statuslast_profile_reload_at, profile_reload_count가 업데이트됩니다.
Codex 네트워크 문제가 의심되면:
./ralph doctornetwork:dns:chatgpt.com, network:codex-api, codex-home 체크를 확인하세요.
주의:
supervisor_enabled,supervisor_restart_delay_sec는 legacy compatibility 설정이며, 변경 시 primary daemon 재시작 후 반영됩니다.
새 ralphctl 바이너리 설치 후:
ralphctl reload- 연결된 프로젝트(현재 프로젝트 + fleet 등록 프로젝트)의
./ralphwrapper를 새 바이너리로 갱신 - 기존에 실행 중이던 primary daemon/telegram daemon만 자동 재시작
- 현재 프로젝트만 반영하려면:
ralphctl reload --current-only
MIT (LICENSE)
