Back to search
ralph
SkillGitHub
A minimal, file‑based agent loop for autonomous coding.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/iannuttall--ralph)HTML
<a href="/listings/iannuttall--ralph"><img src="/api/listings/iannuttall--ralph/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
ralph install
This creates `.agents/ralph/` in the current repo so you can customize prompts and loop behavior. During install, you’ll be asked if you want to add the required skills.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 190 lines · 4 findings marked
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Ralph
- 
- Ralph is a minimal, file‑based agent loop for autonomous coding. Each iteration starts fresh, reads the same on‑disk state, and commits work for one story at a time.
- ## How it works
- Ralph treats **files and git** as memory, not the model context:
- - **PRD (JSON)** defines stories, gates, and status
- - **Loop** executes one story per iteration
- - **State** persists in `.ralph/`
- 
- ## Global CLI (recommended)
- Install and run Ralph from anywhere:
- ```bash
- npm i -g @iannuttall/ralph
- ralph prd # launches an interactive prompt
- ralph build 1 # one Ralph run
- ```
- ### Template hierarchy
- Ralph will look for templates in this order:
- 1. `.agents/ralph/` in the current project (if present)
- 2. Bundled defaults shipped with this repo
- State and logs always go to `.ralph/` in the project.
- ### Install templates into a project (optional overrides)
- ```bash
- ralph install
- ```
- This creates `.agents/ralph/` in the current repo so you can customize prompts and loop behavior. During install, you’ll be asked if you want to add the required skills.
- ### Install required skills (optional)
- ```bash
- ralph install --skills
- ```
- You’ll be prompted for agent (codex/claude/droid/opencode) and local vs global install. Skills installed: **commit**, **dev-browser**, **prd**.
- If you skipped skills during `ralph install`, you can run `ralph install --skills` anytime.
- ## Quick start (project)
- 1) Create your PRD (JSON) or generate one:
- ```
- ralph prd
- ```
- Requires the **prd** skill (install via `ralph install --skills`).
- Example prompt text:
- ```
- A lightweight uptime monitor (Hono app), deployed on Cloudflare, with email alerts via AWS SES
- ```
- Default output (agent chooses a short filename in `.agents/tasks/`):
- ```
- .agents/tasks/prd-<short>.json
- ```
- 2) Run one build iteration:
- ```
- ralph build 1 # one Ralph run
- ```
- No‑commit dry run:
- ```
- ralph build 1 --no-commit # one Ralph run
- ```
- Override PRD output for `ralph prd`:
- ```
- ralph prd --out .agents/tasks/prd-api.json
- ```
- Optional human overview (generated from JSON):
- ```
- ralph overview
- ```
- This writes a tiny overview alongside the PRD: `prd-<slug>.overview.md`.
- PRD story status fields are updated automatically by the loop:
- - `open` → selectable
- - `in_progress` → locked by a running loop (with `startedAt`)
- - `done` → completed (with `completedAt`)
- If a loop crashes and a story stays `in_progress`, you can set `STALE_SECONDS` in `.agents/ralph/config.sh` to allow Ralph to automatically reopen stalled stories.
- ## Override PRD paths
- You can point Ralph at a different PRD JSON file via CLI flags:
- ```bash
- ralph build 1 --prd .agents/tasks/prd-api.json # one Ralph run
- ```
- Optional progress override:
- ```bash
- ralph build 1 --progress .ralph/progress-api.md # one Ralph run
- ```
- If multiple PRD JSON files exist in `.agents/tasks/` and you omit `--prd`, Ralph will prompt you to choose.
- Optional config file (if you installed templates):
- ```
- .agents/ralph/config.sh
- ```
- ## Choose the agent runner
- Set `AGENT_CMD` in `.agents/ralph/config.sh` to switch agents:
- ```
- AGENT_CMD="codex exec --yolo -"
- Note: Starts a coding agent with its permission prompts off
- Line 125 on GitHub
- AGENT_CMD="claude -p --dangerously-skip-permissions \"\$(cat {prompt})\""
- Note: Starts a coding agent with its permission prompts off
- Line 126 on GitHub
- AGENT_CMD="droid exec --skip-permissions-unsafe -f {prompt}"
- AGENT_CMD="opencode run \"$(cat {prompt})\""
- ```
- Or override per run:
- ```
- ralph prd --agent=codex
- ralph build 1 --agent=codex # one Ralph run
- ralph build 1 --agent=claude # one Ralph run
- ralph build 1 --agent=droid # one Ralph run
- ralph build 1 --agent=opencode # one Ralph run
- ```
- If the CLI isn’t installed, Ralph prints install hints:
- ```
- codex -> npm i -g @openai/codex
- claude -> curl -fsSL https://claude.ai/install.sh | bash
- droid -> curl -fsSL https://app.factory.ai/cli | sh
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 146 on GitHub
- opencode -> curl -fsSL https://opencode.ai/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 147 on GitHub
- ```
- ## State files (.ralph/)
- - `progress.md` — append‑only progress log
- - `guardrails.md` — “Signs” (lessons learned)
- - `activity.log` — activity + timing log
- - `errors.log` — repeated failures and notes
- - `runs/` — raw run logs + summaries
- ## Notes
- - `.agents/ralph` is portable and can be copied between repos.
- - `.ralph` is per‑project state.
- - Use `{prompt}` in `AGENT_CMD` when agent needs a file path instead of stdin.
- - Examples: see `examples/commands.md`.
- - **OpenCode server mode**: For faster performance with OpenCode, run `opencode serve` in a separate terminal and uncomment the `AGENT_OPENCODE_CMD` lines in `.agents/ralph/agents.sh` to use `--attach http://localhost:4096`. This avoids cold boot on every run.
- ## Tests
- Dry-run smoke tests (no agent required):
- ```bash
- npm test
- ```
- Fast agent health check (real agent call, minimal output):
- ```bash
- npm run test:ping
- ```
- Optional integration test (requires agents installed):
- ```bash
- RALPH_INTEGRATION=1 npm test
- ```
- Full real-agent loop test:
- ```bash
- npm run test:real
- ```
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.