lukas-grigis/ralphctl

장기 실행 AI 코딩 작업을 위한 에이전트 하네스(Agent harness) —
여러 저장소에 걸쳐 Claude Code를 오케스트레이션하며,
GitHub Copilot 및 OpenAI Codex를 프리뷰(preview)로 제공합니다.

"내가 도와줄게!"— Ralph Wiggum

참고

활발히 개발 중입니다. 새로운 기능과 개선 사항이 정기적으로 배포됩니다. 0.9.0 버전에서는 선택적 병렬 작업 실행(parallel task execution) 기능이 추가되었습니다. 의존성 웨이브(dependency wave) 내의 독립적인 작업들이 각각 별도의 git 워크트리(git worktree)에서 동시에 실행된 후 하나의 브랜치로 통합됩니다. 업그레이드는 간단합니다: 최신 버전을 설치하고, 설정을 다시 수행한 뒤 진행하세요. Upgrading 및 CHANGELOG를 참조하십시오.

AI 코딩 에이전트(AI coding agents)는 강력하지만, 장기 작업 시 컨텍스트(context)를 놓치고, 문제가 발생하면 관리(babysitting)가 필요하며, 여러 저장소에 걸친 변경 사항을 조정할 방법이 없습니다. ralphctl은 사용자가 선택한 AI CLI — Claude Code, 그리고 프리뷰 단계인 GitHub Copilot 및 OpenAI Codex — 를 구조화된 하네스(harness)로 감쌉니다. 이 하네스는 작업을 의존성 순서에 따른 작업으로 분해하고, 다음 단계로 넘어가기 전에 문제를 포착하는 생성자-평가자 루프(generator-evaluator loop)를 통해 각 작업을 구동하며, 세션 간에 컨텍스트를 유지하여 아무것도 유실되지 않도록 합니다.

당신은 무엇을 만들지 설명하기만 하면 됩니다. ralphctl이 나머지를 처리하거나, 당신이 원하는 대로 당신과 함께 작업합니다.

npm install -g ralphctl

Claude Code(또는 아래를 참조하여 프리뷰 제공자)를 설치하고 인증한 다음, 다음을 실행합니다:

ralphctl

그게 전부입니다. TUI가 실행되어 프로젝트 등록, 첫 번째 티켓(ticket) 구체화, 작업 계획(task plan) 생성, 구현 시작 과정을 안내합니다. 홈 화면에서 +를 눌러 새로운 스프린트(sprint)를 생성하거나, n을 눌러 플로우(flow) (구체화 / 계획 / 구현 / 준비도 / …)를 시작하거나, Sprints 서브메뉴를 열고 화면의 힌트를 따라 스프린트를 선택하거나 생성할 수 있습니다. 외워야 할 명령어는 없습니다.

요구 사항: Node.js ≥ 24, Git, 그리고 PATH에 등록되어 인증된 지원되는 AI CLI 하나.

조사 및 단발성 작업을 위해 CLI를 선호하시나요?

대화형 플로우(구체화 / 계획 / 아이디어 구상 / 구현 / 준비도 / 스프린트 생성)는 TUI 전용입니다. CLI는 조사 및 단발성 작업(one-shot operations)을 지원합니다:

# 프로젝트 + 스프린트 조사
ralphctl project list
ralphctl sprint list
...

사용자가 무엇을 구축할지 설명하면 ralphctl이 나머지를 처리합니다
───────────────────────── ─────────────────────────────────
┌──────────┐ ┌──────────┐ ┌────────┐ ┌──────┐ ┌───────────┐
...

Refine (정제) 단계는 구현 방식에 구애받지 않습니다(implementation-agnostic). AI가 티켓(ticket)별로 사용자와 요구사항을 명확히 하고, 각 티켓을 pending (대기) 상태에서 approved (승인) 상태로 전환합니다. Plan (계획) 단계는 모든 티켓이 승인되어야 진행됩니다. AI는 영향을 받는 리포지토리(repos)를 탐색하고 의존성 순서가 지정된 작업 그래프(dependency-ordered task graph)를 생성합니다. Implement (구현) 단계는 생성자-평가자(generator-evaluator) 사이클을 통해 의존성 순서에 따라 해당 작업들을 실행합니다. 하네스(harness)가 작업을 완료로 표시하고 다음으로 넘어가기 전에, 두 번째 AI 패스(pass)가 각 작업을 명세(spec)에 따라 검토합니다. 스프린트를 더 빨리 끝내고 싶을 때는 동일한 의존성 웨이브(dependency wave) 내의 독립적인 작업들을 병렬로 실행(선택 사항)할 수 있습니다.

주요 특징:

의존성 순서 실행 (Dependency-ordered execution)— 작업은 위상 정렬 순서(topological order)로 실행됩니다. 차단 요소(blockers)가 완료될 때까지 어떤 작업도 시작되지 않습니다. 선택적 병렬 처리(concurrency.maxParallelTasks > 1)를 사용하면 의존성 웨이브 내의 독립적인 작업들을 하나의 브랜치로 폴딩된 각각의 git 워크트리(worktree)에서 동시에 실행할 수 있습니다. 기본값은 직렬(serial) 방식입니다.

생성자-평가자 사이클 (Generator-evaluator cycle)— 독립적인 AI 검토자가 각 작업을 확인합니다. 만약 실패할 경우, 생성자(generator)가 비판(critique)을 전달받아 반복(iterate)합니다 (작업이 blocked (차단됨)로 표시되기 전까지 최대 harness.maxAttempts 회 시도).

컨텍스트 지속성 (Context persistence)— 스프린트 상태, 브랜치, 진행 이력 및 작업별 컨텍스트(per-task context)가 세션 간에 유지됩니다. 중단된 실행은 자동으로 재개됩니다.

멀티 리포지토리 지원 (Multi-repo support)— 하나의 스프린트가 리포지토리별 설정 및 검증 스크립트와 함께 여러 리포지토리에 걸쳐 있을 수 있습니다.

전체적인 아키텍처 구조를 보려면 .claude/docs/ARCHITECTURE.md 및 .claude/docs/REQUIREMENTS.md를 참조하세요.

중요

three AI provider(세 곳의 AI 제공업체)가 ralphctl 내부에서 모두 동일하게 프로덕션 수준으로 준비된 것은 아닙니다.

제공업체 (Provider)	상태 (Status)	Headless 플래그 (Headless flag)	네이티브 컨텍스트 파일 (Native context file)
Claude Code (claude-code)	Stable — 주요 검증된 제공업체	--permission-mode bypassPermissions + 도구별 거부 목록 (deny list)	레포지토리 루트의 CLAUDE.md
GitHub Copilot CLI (github-copilot)	Preview — 성숙 단계; 일상적인 작업에는 잘 작동하나, 아직 공식적인 엔드 투 엔드 (end-to-end) 검증은 완료되지 않음	--autopilot --allow-all + --max-autopilot-continues=200	.github/copilot-instructions.md
OpenAI Codex (openai-codex)	Preview — 성숙 단계; 일상적인 작업에는 잘 작동하나, 아직 공식적인 엔드 투 엔드 (end-to-end) 검증은 완료되지 않음	-s workspace-write (토폴로지 범위 지정)	AGENTS.md

"Preview"는 통합 기능이 활발히 사용되고 있으며 점점 더 견고해지고 있음을 의미합니다. 최근 릴리스 버전들은 Copilot과 Codex를 일상적인 워크플로우 전반에서 잘 실행합니다. 하지만 이들에 대한 harness 동작은 Claude Code와 동일한 공식적인 엔드 투 엔드 (end-to-end) 검증을 거치지는 않았습니다. 몇몇 기능은 이들에서 여전히 아무런 동작을 하지 않습니다 (번들형 기술 주입 (bundled skill injection), bodyFile 포렌식 아티팩트 (forensic artifacts)). 또한, Codex는 기존 레포지토리 파일에 대한 편집을 세밀하게 거부할 수 없습니다. Codex의 샌드박스 (sandbox) 모드는 이진적(binary)이므로, 경로 범위 (path scope) (현재 작업 디렉토리 (cwd) + --add-dir)가 유일한 안전 영역입니다. 병렬 실행 (Parallel execution)은 제공업체에 구애받지 않습니다. 각 구현 역할 (implement role)이 사용하도록 설정된 제공업체가 무엇이든, 동일한 제공업체별 주의 사항 하에 작동합니다. Preview 제공업체에서 문제에 부딪힌다면 이슈(issue)를 생성해 주세요.

모든 제공업체에 대한 원샷 설정 (One-shot configuration): ralphctl settings apply-preset <name>

여기서 <name>은 mixed, claude-only, copilot-only, 또는 codex-only입니다.

큰 티켓을 작은 작업으로 분할 — 올바른 순서로 실행되도록 의존성 순서(dependency-ordered)에 따라 분할합니다.
실수가 누적되기 전에 오류 포착 — 각 작업 후 독립적인 AI 리뷰를 수행하며, 품질이 통과되거나 예산이 소진될 때까지 반복합니다.
여러 리포지토리 간의 조정 — 자동 의존성 추적을 통해 하나의 스프린트(sprint)가 여러 리포지토리에 걸쳐 진행될 수 있습니다.
스프린트 완료 속도 향상 (선택 사항) — 의존성 웨이브(dependency wave) 내에서 독립적인 작업들을 각각 별도의 git worktree에서 병렬로 실행한 후, 하나의 스프린트 브랜치로 다시 병합합니다 (여전히 하나의 PR임). 기본값은 직렬(serial) 방식이며 변경 사항은 없습니다.
스프린트당 브랜치 생성 — 영향을 받는 모든 리포지토리에 걸쳐 선택적으로 공유 브랜치를 사용합니다. 작업이 완료되면 ralphctl create-pr --sprint <id>를 통해 gh 또는 glab으로 PR / MR을 엽니다.
Rate Limit(속도 제한)으로부터 복구 — 지수 백오프(exponential backoff) 및 세션 재개(session resume) 기능을 통해, 제공자(provider)가 재시작될 때 진행 중인 작업의 전체 컨텍스트를 유지합니다.
'무엇(what)'과 '어떻게(how)'의 분리 — AI가 먼저 요구사항을 명확히 하고(Refine), 그 다음 구현 계획을 생성(Plan)하며, 그 사이에 인간의 승인 단계(approval gates)를 둡니다.
중단된 지점부터 다시 시작 — 전체 상태 유지(state persistence)를 지원합니다. 중단된 구현(Implement) 실행은 진행 중인 작업을 재설정하고 다음 실행 시 큐(queue)에 다시 진입합니다.
페어 프로그래밍 또는 자동 실행 — AI 에이전트와 상호작용하며 함께 작업하거나, 혹은 알아서 실행되도록 둘 수 있습니다.
기억이 필요 없는 시작 — 인자 없이 ralphctl을 실행하면 가이드 메뉴가 나타납니다.

TUI의 Settings 뷰를 통해 설정하거나, 단발성 CLI 명령어로 설정할 수 있습니다.

가장 빠른 방법 — 프리셋(preset) 적용:

ralphctl settings apply-preset mixed # 흐름(flow)별 최적의 제공자 선택
ralphctl settings apply-preset claude-only # 모든 흐름을 Claude Code로 실행
ralphctl settings apply-preset copilot-only # 모든 흐름을 GitHub Copilot으로 실행
...

프리셋은 ai 섹션 전체를 한 번에 설정합니다. 기본값으로 지정된 프리셋은 없으며, 새로 설치했을 경우 웰컴(welcome) 뷰에서 PATH에 감지된 제공자 CLI를 기반으로 프리셋을 자동으로 생성합니다.

흐름별(Per-flow) 설정. 각 흐름은 자체적인 {provider, model, effort?} 행을 가집니다: refine, plan, readiness, ideate, 그리고 createPr

. implement 흐름은 대신 중첩된 generator / evaluator 쌍(ai.implement.generator.* 및 ai.implement.evaluator.*)으로 분리되며, 각각 고유한 {provider, model, effort?} 행을 가집니다. 다음 명령어로 개별 키를 수정할 수 있습니다:

ralphctl settings set ai.implement.generator.provider claude-code
ralphctl settings set ai.implement.generator.model <model-id>
ralphctl settings set ai.implement.generator.effort high
...

선택된 제공자(provider)의 CLI는 반드시 PATH에 포함되어 있어야 하며 인증된 상태여야 합니다. AI를 생성하는 모든 흐름은 실행 시 해당 행의 CLI를 조사하며, 바이너리가 누락된 경우 명확한 에러와 함께 종료됩니다.

generator-evaluator 루프 조정 (harness 항목 아래):

ralphctl settings set harness.maxAttempts 2 # 작업당 수정 시도 횟수 제한 (1–10, 기본값 3)
ralphctl settings set harness.maxTurns 8 # 시도당 generator-evaluator 턴 수 (1–10)
ralphctl settings set harness.rateLimitRetries 3 # 어댑터 측 429 재시도 횟수 (0–10)

태스크 병렬 실행 (선택 사항 — 기본값은 직렬 실행):

ralphctl settings set concurrency.maxParallelTasks 3 # 1–5; 1 = 직렬 (기본값), >1 = 병렬 git worktree

> 1인 경우, 의존성 웨이브(dependency wave) 내의 독립적인 태스크들이 동시에 실행됩니다. 각 태스크는 고유한 git worktree에서 실행되며, 고유한 setupScript가 실행된 후 단일 스프린트 브랜치로 병합(fold)됩니다 (여전히 스프린트당 하나의 PR 생성). worktree 설정에 실패한 태스크는 다른 형제 태스크를 중단시키지 않고 해당 태스크만 차단됩니다. 만약 동일한 웨이브의 두 태스크가 같은 파일을 수정할 경우, 두 번째 태스크는 병합(fold) 단계에서 차단되며 재실행 시 재시도됩니다. 의존성은 항상 준수되며, 오직 독립적인 태스크들만 겹쳐서 실행됩니다.

모든 상태는 기본적으로 ~/.ralphctl/에 저장됩니다 (config/ 아래의 설정, data/ 아래의 스프린트 + 프로젝트, state/ 아래의 advisory locks). 루트 디렉토리를 변경하려면 다음을 사용하세요:

export RALPHCTL_HOME="/path/to/custom/dir"

변수 (Variable)	기본값 (Default)	목적 (Purpose)
RALPHCTL_HOME	~/.ralphctl/	애플리케이션 루트 (데이터 + 설정 + 상태) 재정의
RALPHCTL_SKIP_LEGACY_CHECK	unset	부팅 시 v0.6.x 레거시 레이아웃 (legacy-layout) 탐지기 우회
RALPHCTL_NO_TUI	unset	implement 명령 시 암시적인 대화형 프롬프트 억제
NO_COLOR	unset	ANSI 색상 억제
CI	자동 감지 (auto-detected)	implement 명령 시 암시적인 대화형 프롬프트 억제

로그 상세도 (Log verbosity)는 settings.logging.level입니다.

(silent / debug / info / warn / error, 기본값 info), ralphctl settings set logging.level <level>을 통해 설정하거나 TUI의 Settings 뷰에서 설정할 수 있습니다. 이는 환경 변수가 아닙니다.

최신 버전을 설치하고, 설정을 다시 수행한 뒤 진행하세요. 최신 릴리스만 지원됩니다. 백포팅 (backporting)은 제공되지 않으며, 대부분의 "이 문제가 해결되었나요?"라는 질문에 대한 답은 업그레이드입니다.

npm install -g ralphctl@latest
ralphctl settings apply-preset <name> # 설정 초기화가 필요한 경우
ralphctl # 필요 시 TUI가 프로젝트 재등록을 안내합니다

이전 릴리스의 ~/.ralphctl/ 데이터가 제대로 로드되지 않는 경우, 백업하고 새로 시작하세요:

mv ~/.ralphctl ~/.ralphctl.bak

백업을 해두면 티켓 본문(ticket bodies), 계획 출력(plan output), 진행 노트(progress notes)를 참조용으로 유지할 수 있습니다. 메이저 버전 간의 이동(예: 0.6.x → 0.7.x)을 수행 중이며 더 자세한 내용을 알고 싶다면 MIGRATION.md를 참조하세요.

CLI 명령 참조 (CLI Command Reference)

CLI 인터페이스는 의도적으로 v0.6.x보다 작게 설계되었습니다. 대화형 흐름(refine / plan / ideate / implement / readiness / create sprint)은 설계상 TUI 전용으로 유지됩니다. CLI는 검사(inspection) 및 단발성 작업(one-shot operations)을 제공합니다.

명령 (Command)	설명 (Description)
ralphctl	대화형 TUI (주요 인터페이스)
ralphctl doctor	환경 상태 점검
ralphctl settings show	현재 설정 출력
ralphctl settings set <key> <value>	단일 설정 키 설정
ralphctl settings apply-preset <name>	전체 ai 섹션에 프리셋 적용 (mixed / claude-only / copilot-only / codex-only)
ralphctl completion <shell>	셸 탭 완성 (tab-completion) 스크립트 출력

명령 (Command)	설명 (Description)
ralphctl project list	등록된 프로젝트 목록 표시
ralphctl project show <id>	단일 프로젝트 표시 (리포지토리 포함)
ralphctl project remove <id>	프로젝트 등록 삭제
ralphctl sprint list	모든 스프린트 (sprint) 목록 표시
ralphctl sprint show <id>	단일 스프린트 표시 (티켓, 상태, 브랜치)
ralphctl sprint progress <id>	차단 요소 진단(blocker diagnostics)을 포함한 스프린트 진행 상황
ralphctl sprint set-current <id>	현재 스프린트 포인터 전환
ralphctl ticket add	현재 스프린트에 티켓 추가
ralphctl ticket list / show <id>	티켓 검사
ralphctl ticket remove <id>	초안(draft) 스프린트에서 티켓 제거
ralphctl task list / show <id>	태스크 (task) 검사 (플래닝 과정에서 생성됨)
ralphctl task unblock <id>	차단된(blocked) 태스크를 todo 상태로 초기화

명령 (Command)	설명 (Description)
ralphctl sprint activate <id>	초안(draft) 스프린트를 active 상태로 전환
ralphctl sprint close <id>	review → done 상태 전환
ralphctl sprint remove <id>	스프린트 영구 삭제