Ralph Loop

while :; do cat PROMPT.md | claude-code ; done

# 설치
/plugin install ralph-wiggum@claude-plugins-official

# 의존성 (Windows의 경우 필수)
# jq 먼저 설치 필요

/ralph-loop "Your task description" --max-iterations 20 --completion-promise "COMPLETE"

# 설치 (Bun 필요)
bun install -g ralph-tui

# 프로젝트 설정
cd your-project
ralph-tui setup

# AI로 PRD 생성
ralph-tui create-prd --chat

# Ralph 실행!
ralph-tui run --prd ./prd.json

npm install ralph-loop-agent

# Claude Code 설치
curl -fsSL https://claude.ai/install.sh | bash

# 인증
claude

# 플러그인 마켓플레이스 추가
/plugin install marketplace

# Ralph Wiggum 플러그인 설치
/plugin install ralph-wiggum@claude-plugins-official

# 설치 확인
/plugins

# 단순 작업
/ralph-loop "Build a REST API for todos.
When complete:
- All CRUD endpoints working
- Input validation in place
- Tests passing (coverage > 80%)
- README with API docs
- Output: <promise>COMPLETE</promise>" \
--max-iterations 20 \
--completion-promise "COMPLETE"

/ralph-loop "Implement user authentication using TDD.
Process:
1. Write failing test for next requirement
2. Implement minimal code to pass
3. Run tests
4. If failing, fix and retry
5. Refactor if needed
6. Repeat for all requirements

Requirements:
- JWT token generation
- Password hashing with bcrypt
- Login/logout endpoints
- Token refresh mechanism

Output <promise>DONE</promise> when all tests green." \
--max-iterations 50 \
--completion-promise "DONE"

/ralph-loop "Migrate all tests from Jest to Vitest.
Steps:
1. Identify Jest test files
2. Convert imports to Vitest equivalents
3. Update mock syntax
4. Run tests
5. Fix any failing tests
6. Update package.json scripts

Output <promise>MIGRATION_COMPLETE</promise> when:
- All tests converted
- No Jest dependencies remain
- All tests passing" \
--max-iterations 50 \
--completion-promise "MIGRATION_COMPLETE"

# overnight-work.sh
#!/bin/bash

# Phase 1: 데이터 모델
cd /path/to/project
claude -p "/ralph-loop 'Phase 1: Build data models.
Output <promise>PHASE1_DONE</promise>' --max-iterations 20"

# Phase 2: API 레이어
claude -p "/ralph-loop 'Phase 2: Build API endpoints for existing models.
Output <promise>PHASE2_DONE</promise>' --max-iterations 25"

# Phase 3: 프론트엔드
claude -p "/ralph-loop 'Phase 3: Build UI components.
Output <promise>PHASE3_DONE</promise>' --max-iterations 30"

# 실행
chmod +x overnight-work.sh
./overnight-work.sh

# 실행 중인 Ralph Loop 취소
/cancel-ralph

# Bun 설치 (필수)
# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# Windows
powershell -c "irm bun.sh/install.ps1 | iex"

# Ralph TUI 설치
bun install -g ralph-tui

# 버전 확인
ralph-tui --version

cd your-project

# 인터랙티브 설정 마법사
ralph-tui setup

# AI 대화로 PRD 생성 (추천)
ralph-tui create-prd --chat

# 또는 alias 사용
ralph-tui prime

# 특정 에이전트로
ralph-tui create-prd --agent claude

# 출력 디렉토리 지정
ralph-tui create-prd --output ./docs

# Claude Code에서 슬래시 명령어로 사용
/ralph-tui-prd           # PRD 인터랙티브 생성
/ralph-tui-create-json   # PRD를 prd.json으로 변환
/ralph-tui-create-beads  # PRD를 Beads 이슈로 변환

# PRD 파일로 실행
ralph-tui run --prd ./prd.json

# Beads epic으로 실행
ralph-tui run --epic my-epic-id

# 에이전트/모델 오버라이드
ralph-tui run --agent claude --model sonnet
ralph-tui run --agent opencode --model anthropic/claude-3-5-sonnet

# 반복 횟수 제한
ralph-tui run --iterations 10

# 헤드리스 모드 (CI/CD용)
ralph-tui run --headless

# 샌드박스에서 실행 (보안)
ralph-tui run --sandbox

# 이전 세션 재개
ralph-tui resume

# 세션 상태 확인
ls -la .ralph-tui/

# 기본 에이전트
agent = "claude"

# 기본 모델
model = "sonnet"

# 스킬 디렉토리 (커스텀 PRD 스킬용)
skills_dir = "/path/to/my-skills"

# 알림 소리
[notification]
sound = "ralph"  # off, system, ralph

# 로그 설정
[logs]
dir = ".ralph-tui/iterations"

# 1. 프로젝트 생성
mkdir mind-map-app && cd mind-map-app
npm init -y

# 2. Ralph TUI 설정
ralph-tui setup

# 3. PRD 생성 (AI 대화)
ralph-tui create-prd --chat
# AI: "어떤 기능을 원하시나요?"
# User: "visual graph-based thought mapping app that allows creating notes
#        and linking related thoughts"
# AI: "MVP 범위로 할까요?"
# User: "Yes, MVP please"

# 4. Ralph 실행
ralph-tui run --prd ./prd.json

# 5. TUI에서 진행 상황 모니터링...
# 약 1시간 45분 후 완료!

npm install ralph-loop-agent
# 또는
yarn add ralph-loop-agent
# 또는
pnpm add ralph-loop-agent

import { iterationCountIs, RalphLoopAgent } from "ralph-loop-agent"

const agent = new RalphLoopAgent({
  model: "anthropic/claude-opus-4.5",
  instructions: "You are a helpful coding assistant.",
  stopWhen: iterationCountIs(10),
  verifyCompletion: async ({ result }) => ({
    complete: result.text.includes("DONE"),
    reason: "Task completed successfully",
  }),
})

const { text, iterations, completionReason } = await agent.loop({
  prompt: "Create a function that calculates fibonacci numbers",
})

console.log(text)
console.log(`Completed in ${iterations} iterations`)
console.log(`Reason: ${completionReason}`)

import { tool } from "ai"
import { iterationCountIs, RalphLoopAgent } from "ralph-loop-agent"
import { z } from "zod"

const agent = new RalphLoopAgent({
  model: "anthropic/claude-opus-4.5",
  instructions: "You help users with file operations.",
  tools: {
    readFile: tool({
      description: "Read a file from disk",
      parameters: z.object({ path: z.string() }),
      execute: async ({ path }) => {
        const fs = require("fs").promises
        const content = await fs.readFile(path, "utf-8")
        return { content }
      },
    }),
    writeFile: tool({
      description: "Write content to a file",
      parameters: z.object({
        path: z.string(),
        content: z.string(),
      }),
      execute: async ({ path, content }) => {
        const fs = require("fs").promises
        await fs.writeFile(path, content)
        return { success: true }
      },
    }),
  },
  stopWhen: iterationCountIs(10),
  verifyCompletion: ({ result }) => ({
    complete: result.text.includes("All files updated"),
  }),
})

const stream = await agent.stream({
  prompt: "Build a calculator module with add, subtract, multiply, divide functions",
})

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk)
}

import { iterationCountIs, RalphLoopAgent } from "ralph-loop-agent"

const migrationAgent = new RalphLoopAgent({
  model: "anthropic/claude-opus-4.5",
  instructions: `You are migrating a codebase from Jest to Vitest.
  
For each iteration:
1. Find one Jest test file that hasn't been migrated
2. Convert it to Vitest syntax
3. Run the tests to verify
4. Move to the next file

When all files are migrated and tests pass, include "MIGRATION_COMPLETE" in your response.`,
  stopWhen: iterationCountIs(50),
  verifyCompletion: ({ result }) => ({
    complete: result.text.includes("MIGRATION_COMPLETE"),
    reason: "All Jest tests migrated to Vitest",
  }),
})

async function runMigration() {
  console.log("Starting Jest to Vitest migration...\n")

  const { text, iterations, completionReason } = await migrationAgent.loop({
    prompt: "Begin the Jest to Vitest migration. Start by analyzing the current test structure.",
  })

  console.log("\n--- Migration Complete ---")
  console.log(`Iterations: ${iterations}`)
  console.log(`Reason: ${completionReason}`)
}

runMigration()

const stream = await agent.stream({
  prompt: "Build a todo API",
})

// 실시간 출력
for await (const chunk of stream.textStream) {
  process.stdout.write(chunk)
}

// 최종 결과
const result = await stream.finalResult
console.log(`\nCompleted in ${result.iterations} iterations`)

# Feature: User Authentication

## Overview

Implement secure user authentication with JWT tokens.

## User Stories

### US-001: User Registration

**As a** new user  
**I want to** create an account  
**So that** I can access the application

**Acceptance Criteria:**

- [ ] Email validation
- [ ] Password strength requirements (8+ chars, 1 uppercase, 1 number)
- [ ] Duplicate email check
- [ ] Welcome email sent on success

**Technical Notes:**

- Use bcrypt for password hashing
- Store in PostgreSQL users table

### US-002: User Login

**As a** registered user  
**I want to** log in with my credentials  
**So that** I can access my account

**Acceptance Criteria:**

- [ ] Email/password validation
- [ ] JWT token generation
- [ ] Refresh token mechanism
- [ ] Rate limiting (5 attempts per minute)

### US-003: Password Reset

**As a** user who forgot my password  
**I want to** reset my password  
**So that** I can regain access

**Acceptance Criteria:**

- [ ] Reset email with secure token
- [ ] Token expires in 1 hour
- [ ] Password update functionality

{
  "featureName": "User Authentication",
  "branchName": "feature/auth",
  "userStories": [
    {
      "id": "US-001",
      "title": "User Registration",
      "priority": 1,
      "passes": false,
      "acceptanceCriteria": [
        "Email validation",
        "Password strength requirements",
        "Duplicate email check",
        "Welcome email sent"
      ]
    },
    {
      "id": "US-002",
      "title": "User Login",
      "priority": 2,
      "passes": false,
      "acceptanceCriteria": [
        "Email/password validation",
        "JWT token generation",
        "Refresh token mechanism",
        "Rate limiting"
      ]
    }
  ]
}

# 항상 max-iterations 설정
/ralph-loop "..." --max-iterations 20

# Ralph TUI에서도
ralph-tui run --iterations 10

# 비용 모니터링
# Claude Code: ~/.config/claude/usage.json 확인
# API 사용량: Anthropic Console에서 확인

# ✅ 좋은 프롬프트

Build a REST API for todos.

Success Criteria:

- All CRUD endpoints working
- Input validation with Zod
- Tests passing (>80% coverage)
- No TypeScript errors

When complete, output: <promise>DONE</promise>
When stuck after 15 iterations:

- Document blockers
- List attempted solutions
- Suggest alternatives

# ❌ 나쁜 프롬프트

Build a todo app and make it good.

// package.json
{
  "scripts": {
    "test": "vitest",
    "lint": "eslint . --ext .ts,.tsx",
    "typecheck": "tsc --noEmit",
    "validate": "npm run typecheck && npm run lint && npm run test"
  }
}

## Validation (run before every commit)

npm run validate

⚠️ DO NOT commit if validation fails.

# Ralph TUI 샌드박스 모드
ralph-tui run --sandbox

# Docker로 격리
docker run -it --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  node:20 \
  bash -c "./ralph.sh"

# 진행 상황 확인
cat progress.txt

# PRD 상태 확인 (JSON)
cat prd.json | jq '.userStories[] | {id, title, passes}'

# Git 히스토리 확인
git log --oneline -20

# Ralph TUI 로그 확인
ls -la .ralph-tui/iterations/
cat .ralph-tui/iterations/iteration-1-*.log