@kiblazer/ralph-run

Unattended iterative AI agent execution loop. Run Claude Code, Codex, or OpenCode in a headless retry loop until the job succeeds.

Why

AI agents sometimes fail mid-task — network hiccups, API rate limits, transient tool errors, or the agent simply getting stuck. ralph-run automates the boring part: run the agent, detect failure, back off, and retry. It keeps logs for every attempt so you can audit what happened.

Features

• Multi-agent support — Claude Code (default), OpenAI Codex CLI, OpenCode
• Automatic retry with exponential backoff — configurable base / cap
• Timeout protection — total process timeout and no-output idle timeout
• Per-attempt log files — stdout and stderr saved for debugging
• Session resumption — optional shared context across attempts (Claude Code)
• Countdown timer — visual pause between rounds
• Zero runtime dependencies except commander

Installation

Global (recommended)

npm install -g @kiblazer/ralph-run

npx (no install)

npx @kiblazer/ralph-run --prompt "write a test suite" --runs 3

Local

npm install --save-dev @kiblazer/ralph-run

Prerequisites

You must have the target agent CLI installed and available in your $PATH:

| Agent | Required CLI | |---------|--------------------------------------| | claude | claude-code | | codex | @openai/codex | | opencode| opencode |

Usage

Usage: ralph-run [options]

Options:
  -V, --version                          output the version number
  --prompt <text>                        Prompt text to send to agent
  --prompt-file <path>                   Read prompt from file (overrides --prompt)
  --agent <name>                         Agent to use: claude, codex, opencode (default: "claude")
  --runs <n>                             Number of successful runs to achieve (default: "1")
  --project-dir <path>                   Working directory (default: ".")
  --logs-dir <path>                      Logs directory (default: ./logs-ralph-<timestamp>)
  --permission-mode <mode>               Permission mode: bypassPermissions, acceptEdits, yolo (default: "bypassPermissions")
  --shared-context                       Enable session resumption across attempts
  --retry-base <seconds>                 Base seconds for exponential backoff (default: "120")
  --retry-cap <seconds>                  Max seconds for exponential backoff (default: "3600")
  --process-timeout <seconds>            Total process timeout (0=disabled) (default: "21600")
  --no-output-timeout <seconds>          No-output idle timeout (0=disabled) (default: "10800")
  --heartbeat <seconds>                  Heartbeat interval (0=disabled) (default: "30")
  --countdown <seconds>                  Countdown between rounds (default: "10")
  --max-attempts <n>                     Max attempts per round (0=unlimited) (default: "0")
  -h, --help                             display help for command

Examples

Run a single task with Claude Code

ralph-run --prompt "Refactor src/utils.ts to use async/await" --runs 1

Run 3 independent rounds with a prompt file

ralph-run --prompt-file ./prompts/refactor.md --runs 3 --agent claude

Use Codex with yolo mode

ralph-run --prompt "Add JSDoc to all exported functions" --agent codex --permission-mode yolo

Custom timeouts and retry policy

ralph-run \
  --prompt-file ./prompts/migrate.md \
  --runs 2 \
  --process-timeout 3600 \
  --no-output-timeout 1800 \
  --retry-base 60 \
  --retry-cap 600

Enable session resumption

ralph-run --prompt "Continue implementing the API" --shared-context --runs 1

Important: Shell escaping

If your prompt contains backticks (`), bash will attempt command substitution. Always use single quotes for inline prompts:

# WRONG — bash tries to execute "date" inside backticks
ralph-run --prompt "Fix the \`createdAt\` field"

# CORRECT
ralph-run --prompt 'Fix the `createdAt` field'

For long or complex prompts, prefer --prompt-file:

ralph-run --prompt-file ./my-prompt.md

How it works

1. Countdown — waits the configured seconds before starting a round.
2. Execute — spawns the selected agent with the prompt.
3. Detect — classifies success (exit_code === 0) or failure.
4. Log — writes stdout and stderr to timestamped files in the logs directory.
5. Retry on failure — sleeps with exponential backoff, then re-runs the same round.
6. Repeat — continues until the required number of successful runs is reached.

Logs

Each attempt produces two files:

logs-ralph-20260515T143022/
├── round-1_attempt-1_20260515T143022_stdout.log
├── round-1_attempt-1_20260515T143022_stderr.log
├── round-1_attempt-2_20260515T143100_stdout.log
└── ...

Development

git clone https://github.com/kiblazer/ralph-run.git
cd ralph-run
npm install
npm run build
node dist/index.js --help

License

MIT