@daonhan/ralph

CLI for Ralph — a harness that drives Claude Code by default, or Codex when selected with --agent codex, against a target repository in an iterating implementer → reviewer loop inside an ephemeral Docker sandbox.

Exposes two bin entries (thin wrappers over @daonhan/ralph-core):

• ralph-afk — plan/PRD-driven loop. Iterates until the agent emits <promise>NO MORE TASKS</promise>.
• ralph-ghafk — GitHub-issue-driven loop. Pulls open issues and lets the agent pick the next task.

Security: Ralph runs the selected agent without interactive approval inside the sandbox and, by default, bind-mounts the host Docker socket (root-equivalent host access). Point it only at repositories and prompts you trust. See SECURITY.md.

Install

npm i -g @daonhan/ralph

Use

cd /path/to/your/workspace
ralph-afk "<plan-and-prd>" 5      # plan/PRD loop
ralph-ghafk 5                     # GitHub-issue loop
ralph-afk --agent codex "<plan-and-prd>" 5
ralph-ghafk --agent codex 5
ralph-afk --help                  # flags, env vars
ralph-afk --print-config          # diagnose workspace / docker context / image / socket / history dir

Every run appends a readable history file under <workspace>/.ralph/history/ (one Markdown file per run, self-gitignored) and injects the last ten stage entries into the next implementer prompt. Needs @daonhan/ralph-core 0.8.0 or later.

Claude is the default; RALPH_AGENT=codex is the fallback when --agent is absent. Requires Docker and a login for the selected provider (and gh for ralph-ghafk). Codex users should follow the root README's file-backed login and provider configuration instructions. Both providers run from native Windows shells (PowerShell, cmd, Git Bash) or WSL; log in with the host CLI from the same shell environment that launches Ralph. First-run setup, per-OS notes, and the full flag/env reference are in the main README and QUICKSTART. Read the full security threat model before running either provider.

License

MIT © Paul Nguyen.