Skip to content
Back to search

ralph

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/iannuttall--ralph/badge.svg)](/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)

  1. # Ralph
  2. ![Ralph](ralph.webp)
  3. 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.
  4. ## How it works
  5. Ralph treats **files and git** as memory, not the model context:
  6. - **PRD (JSON)** defines stories, gates, and status
  7. - **Loop** executes one story per iteration
  8. - **State** persists in `.ralph/`
  9. ![Ralph architecture](diagram.svg)
  10. ## Global CLI (recommended)
  11. Install and run Ralph from anywhere:
  12. ```bash
  13. npm i -g @iannuttall/ralph
  14. ralph prd # launches an interactive prompt
  15. ralph build 1 # one Ralph run
  16. ```
  17. ### Template hierarchy
  18. Ralph will look for templates in this order:
  19. 1. `.agents/ralph/` in the current project (if present)
  20. 2. Bundled defaults shipped with this repo
  21. State and logs always go to `.ralph/` in the project.
  22. ### Install templates into a project (optional overrides)
  23. ```bash
  24. ralph install
  25. ```
  26. 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.
  27. ### Install required skills (optional)
  28. ```bash
  29. ralph install --skills
  30. ```
  31. You’ll be prompted for agent (codex/claude/droid/opencode) and local vs global install. Skills installed: **commit**, **dev-browser**, **prd**.
  32. If you skipped skills during `ralph install`, you can run `ralph install --skills` anytime.
  33. ## Quick start (project)
  34. 1) Create your PRD (JSON) or generate one:
  35. ```
  36. ralph prd
  37. ```
  38. Requires the **prd** skill (install via `ralph install --skills`).
  39. Example prompt text:
  40. ```
  41. A lightweight uptime monitor (Hono app), deployed on Cloudflare, with email alerts via AWS SES
  42. ```
  43. Default output (agent chooses a short filename in `.agents/tasks/`):
  44. ```
  45. .agents/tasks/prd-<short>.json
  46. ```
  47. 2) Run one build iteration:
  48. ```
  49. ralph build 1 # one Ralph run
  50. ```
  51. No‑commit dry run:
  52. ```
  53. ralph build 1 --no-commit # one Ralph run
  54. ```
  55. Override PRD output for `ralph prd`:
  56. ```
  57. ralph prd --out .agents/tasks/prd-api.json
  58. ```
  59. Optional human overview (generated from JSON):
  60. ```
  61. ralph overview
  62. ```
  63. This writes a tiny overview alongside the PRD: `prd-<slug>.overview.md`.
  64. PRD story status fields are updated automatically by the loop:
  65. - `open` → selectable
  66. - `in_progress` → locked by a running loop (with `startedAt`)
  67. - `done` → completed (with `completedAt`)
  68. 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.
  69. ## Override PRD paths
  70. You can point Ralph at a different PRD JSON file via CLI flags:
  71. ```bash
  72. ralph build 1 --prd .agents/tasks/prd-api.json # one Ralph run
  73. ```
  74. Optional progress override:
  75. ```bash
  76. ralph build 1 --progress .ralph/progress-api.md # one Ralph run
  77. ```
  78. If multiple PRD JSON files exist in `.agents/tasks/` and you omit `--prd`, Ralph will prompt you to choose.
  79. Optional config file (if you installed templates):
  80. ```
  81. .agents/ralph/config.sh
  82. ```
  83. ## Choose the agent runner
  84. Set `AGENT_CMD` in `.agents/ralph/config.sh` to switch agents:
  85. ```
  86. AGENT_CMD="codex exec --yolo -"
  87. AGENT_CMD="claude -p --dangerously-skip-permissions \"\$(cat {prompt})\""
  88. AGENT_CMD="droid exec --skip-permissions-unsafe -f {prompt}"
  89. AGENT_CMD="opencode run \"$(cat {prompt})\""
  90. ```
  91. Or override per run:
  92. ```
  93. ralph prd --agent=codex
  94. ralph build 1 --agent=codex # one Ralph run
  95. ralph build 1 --agent=claude # one Ralph run
  96. ralph build 1 --agent=droid # one Ralph run
  97. ralph build 1 --agent=opencode # one Ralph run
  98. ```
  99. If the CLI isn’t installed, Ralph prints install hints:
  100. ```
  101. codex -> npm i -g @openai/codex
  102. claude -> curl -fsSL https://claude.ai/install.sh | bash
  103. 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
  104. 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
  105. ```
  106. ## State files (.ralph/)
  107. - `progress.md` — append‑only progress log
  108. - `guardrails.md` — “Signs” (lessons learned)
  109. - `activity.log` — activity + timing log
  110. - `errors.log` — repeated failures and notes
  111. - `runs/` — raw run logs + summaries
  112. ## Notes
  113. - `.agents/ralph` is portable and can be copied between repos.
  114. - `.ralph` is per‑project state.
  115. - Use `{prompt}` in `AGENT_CMD` when agent needs a file path instead of stdin.
  116. - Examples: see `examples/commands.md`.
  117. - **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.
  118. ## Tests
  119. Dry-run smoke tests (no agent required):
  120. ```bash
  121. npm test
  122. ```
  123. Fast agent health check (real agent call, minimal output):
  124. ```bash
  125. npm run test:ping
  126. ```
  127. Optional integration test (requires agents installed):
  128. ```bash
  129. RALPH_INTEGRATION=1 npm test
  130. ```
  131. Full real-agent loop test:
  132. ```bash
  133. npm run test:real
  134. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.