@weppy/ralph

@weppy/ralph is an independent orchestrator package for fresh-context AI agent execution.

Scope

• File-backed job state under .ralph-cache/ by default
• Adapter-based execution for Codex and Claude Code
• Ralph-owned validation, retry, completion, and resume rules
• Shared core with both CLI and MCP access layers
• Input files and images are passed as path references for the agent to inspect directly
• Run state and placeholder logs are written before agent execution starts

Usage

ralph start \
  --title "Implement auth flow" \
  --agent custom-command \
  --workspace /path/to/project \
  --input docs/spec.md \
  --validate-cmd "npm test" \
  --max-retries 1

ralph status --workspace /path/to/project --json
ralph resume --workspace /path/to/project --max-iterations 5 --json
ralph result --workspace /path/to/project
ralph cancel --workspace /path/to/project

Adapters

• codex: runs codex exec
• claude-code: runs claude -p
• custom-command: runs the shell command from RALPH_CUSTOM_AGENT_COMMAND

custom-command receives these environment variables:

• RALPH_WORKSPACE_PATH
• RALPH_PROMPT_PATH
• RALPH_OUTPUT_PATH
• RALPH_RUN_DIRECTORY_PATH

The command must write a valid result.json payload to RALPH_OUTPUT_PATH. RALPH_OUTPUT_PATH points directly to the run's result.json file.

Specs

• 개요
• 아키텍처
• 상태와 실행
• 인터페이스
• 구현 계획

Scripts

• npm run check
• npm run build
• npm test