Skip to content
Back to search

ralph

A configurable Bash/PowerShell loop that runs an AI coding CLI with a fresh session each iteration

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/santanderai--ralph/badge.svg)](/listings/santanderai--ralph)

HTML

<a href="/listings/santanderai--ralph"><img src="/api/listings/santanderai--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.

These steps run a script from the network that findsafeskills does not scan.

The quickest way — a dependency-free installer (needs only `curl` and `tar`) that copies `ralph-loop.sh` to `~/.local/bin` and installs the bundled skills. Re-run it any time to update:

curl -fsSL https://raw.githubusercontent.com/SantanderAI/ralph/main/install.sh | sh

It accepts `--no-skills`, `--ref <branch|tag>`, `--repo <owner/name>` and `--install-dir <dir>` (also available as the `RALPH_SKIP_SKILLS`, `RALPH_REF`, `RALPH_REPO` and `RALPH_INSTALL_DIR` environment variables), e.g.:

curl -fsSL https://raw.githubusercontent.com/SantanderAI/ralph/main/install.sh | sh -s -- --no-skills

On **Windows / PowerShell** (pwsh 6+), the equivalent installs `ralph-loop.ps1`:

powershell -c "irm https://raw.githubusercontent.com/SantanderAI/ralph/main/install.ps1 | iex"

The PowerShell installer is configured through the same `RALPH_SKIP_SKILLS`, `RALPH_REF`, `RALPH_REPO` and `RALPH_INSTALL_DIR` environment variables.

Alternatively, from a clone with [`just`](https://github.com/casey/just):

just install

Or just copy `ralph-loop.sh` somewhere on your `PATH` and make it executable.

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 · 303 lines · 3 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. > Open source by **Santander AI Lab**. A dependency-free Bash / PowerShell
  3. > developer tool that runs an **AI coding CLI / LLM agent** in a loop, starting
  4. > a fresh agent session on every iteration for long unattended runs.
  5. [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
  6. [![Shell: Bash | PowerShell](https://img.shields.io/badge/shell-bash%20%7C%20pwsh-89e051.svg)](ralph-loop.sh)
  7. [![CI](https://github.com/SantanderAI/ralph/actions/workflows/ci.yml/badge.svg)](https://github.com/SantanderAI/ralph/actions/workflows/ci.yml)
  8. [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/SantanderAI/ralph/badge)](https://securityscorecards.dev/viewer/?uri=github.com/SantanderAI/ralph)
  9. [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196.svg)](https://www.conventionalcommits.org)
  10. Part of [**Santander AI Open Source**](https://github.com/SantanderAI) — open source AI projects from Banco Santander ([santander.com](https://santander.com)).
  11. `ralph` runs an AI coding CLI in a loop, starting a **fresh session on every
  12. iteration** and feeding it the same prompt. It is a thin, dependency-free Bash
  13. wrapper (`ralph-loop.sh`) around the CLIs you already have installed —
  14. [Codex](https://developers.openai.com/codex/cli/),
  15. [Claude Code](https://docs.claude.com/en/docs/claude-code),
  16. [Gemini CLI](https://github.com/google-gemini/gemini-cli), and
  17. [Devin CLI](https://docs.devin.ai/) — so you can drive long, unattended "keep
  18. working on this until it's done" runs.
  19. The name comes from the "Ralph Wiggum" technique: run the same prompt against a
  20. clean agent over and over, letting the work accumulate in the repository
  21. between runs.
  22. ## How it works
  23. Each iteration the script:
  24. 1. Checks for a stop signal (`stop.md`) and exits cleanly if found.
  25. 2. Reloads configuration (see [Live reload](#live-reload-of-configuration)).
  26. 3. Launches the selected CLI as a brand-new session with your prompt piped to
  27. it, running in the directory where you invoked the script.
  28. 4. Writes a timestamped log to `.ralph/logs/` and rotates old logs.
  29. Because every iteration is a fresh session, all continuity has to live in the
  30. workspace itself: the files the agent edits, a plan, notes, etc. The prompt
  31. should tell the agent to read that state and make incremental progress.
  32. ## Requirements
  33. - Bash.
  34. - At least one of the supported CLIs on your `PATH`: `codex`, `claude`,
  35. `gemini`, or `devin`.
  36. - Optionally [`just`](https://github.com/casey/just) for the install recipe.
  37. ## Installation
  38. The quickest way — a dependency-free installer (needs only `curl` and `tar`)
  39. that copies `ralph-loop.sh` to `~/.local/bin` and installs the bundled skills.
  40. Re-run it any time to update:
  41. ```sh
  42. curl -fsSL https://raw.githubusercontent.com/SantanderAI/ralph/main/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 56 on GitHub
  43. ```
  44. It accepts `--no-skills`, `--ref <branch|tag>`, `--repo <owner/name>` and
  45. `--install-dir <dir>` (also available as the `RALPH_SKIP_SKILLS`, `RALPH_REF`,
  46. `RALPH_REPO` and `RALPH_INSTALL_DIR` environment variables), e.g.:
  47. ```sh
  48. curl -fsSL https://raw.githubusercontent.com/SantanderAI/ralph/main/install.sh | sh -s -- --no-skills
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 64 on GitHub
  49. ```
  50. On **Windows / PowerShell** (pwsh 6+), the equivalent installs `ralph-loop.ps1`:
  51. ```powershell
  52. powershell -c "irm https://raw.githubusercontent.com/SantanderAI/ralph/main/install.ps1 | iex"
  53. ```
  54. The PowerShell installer is configured through the same `RALPH_SKIP_SKILLS`,
  55. `RALPH_REF`, `RALPH_REPO` and `RALPH_INSTALL_DIR` environment variables.
  56. Alternatively, from a clone with [`just`](https://github.com/casey/just):
  57. ```sh
  58. just install
  59. ```
  60. Or just copy `ralph-loop.sh` somewhere on your `PATH` and make it executable.
  61. ## Usage
  62. ```sh
  63. ralph-loop.sh MAX_ITERATIONS PROMPT_FILE
  64. ```
  65. - `MAX_ITERATIONS` — positive integer; the maximum number of loops to run.
  66. - `PROMPT_FILE` — a file whose contents are sent to the CLI as the prompt.
  67. Example — run Claude with a high-capability model up to 25 times. Configuration
  68. lives in `.ralph/.env` (created with defaults on first run), so edit it and then
  69. launch:
  70. ```sh
  71. # .ralph/.env
  72. RALPH_TOOL=claude
  73. RALPH_MODEL_CAPABILITY=high
  74. ```
  75. ```sh
  76. ralph-loop.sh 25 prompt.md
  77. ```
  78. The directory you invoke the script from is treated as the workspace. Run
  79. `ralph-loop.sh` with the wrong number of arguments to print full inline help.
  80. ## Configuration
  81. Behavior is controlled entirely through `.ralph/.env` in your workspace, created
  82. with these defaults the first time you run the loop. It is the only
  83. configuration source — the shell environment is ignored. Quote values that
  84. contain spaces. The most common keys:
  85. | Variable | Values | Default | Purpose |
  86. | --- | --- | --- | --- |
  87. | `RALPH_TOOL` | `codex`, `claude`, `gemini`, `devin` | `codex` | Which CLI to run. |
  88. | `RALPH_MODEL_CAPABILITY` | `low`, `med`, `high` | `med` | Normalized model tier, mapped per tool. |
  89. | `RALPH_THINKING` | `true`, `false` | `false` | Best-effort reasoning/thinking toggle. |
  90. | `RALPH_SWITCH_ON_EXHAUSTION` | `true`, `false` | `true` | On a failed iteration, auto-switch agent if it ran out of tokens. |
  91. | `RALPH_MEMORY_MAX` | systemd memory value (`8G`, `512M`, bytes, `%`) or empty | `8G` | Hard RAM limit for the agent, kernel-enforced via a systemd user scope; the agent is OOM-killed if it exceeds it. Empty disables. |
  92. | `RALPH_LOOP_MAX_LOGS` | positive integer | `min(MAX_ITERATIONS, 50)` | Logs to retain in `.ralph/logs`. |
  93. Each tool also has overrides for its command, flags, and the model used for
  94. each capability tier, e.g. `RALPH_CLAUDE_COMMAND`, `RALPH_CLAUDE_FLAGS`,
  95. `RALPH_CLAUDE_MODEL_HIGH`, and the equivalents for `CODEX`, `GEMINI`, and
  96. `DEVIN`. The capability tier (`low`/`med`/`high`) is translated into the right
  97. per-tool model name and reasoning effort / thinking budget automatically.
  98. Devin is special in two ways: it has no reasoning/thinking knob (so
  99. `RALPH_THINKING` is ignored for it and the tier only selects the model), and it
  100. reads the prompt from `--prompt-file` rather than stdin. Its `RALPH_DEVIN_MODEL_*`
  101. defaults point at Devin's Claude models (`claude-haiku-4.5`,
  102. `claude-sonnet-4.6`, `claude-opus-4.8`); run `devin --model x` to print the full
  103. list of valid identifiers. On the Devin Free tier, override all three tiers with
  104. `swe-1.6-slow`, the only model that plan can access.
  105. See the inline help in `ralph-loop.sh` for the complete list.
  106. ## Live reload of configuration
  107. `.ralph/.env` is sourced **before every iteration**, so the loop can be
  108. reconfigured while it is running — no restart needed. Edit the file mid-run and
  109. the change takes effect on the next iteration.
  110. ```sh
  111. # .ralph/.env
  112. RALPH_TOOL=claude
  113. RALPH_MODEL_CAPABILITY=high
  114. RALPH_THINKING=true
  115. ```
  116. Notes:
  117. - Plain `KEY=value` lines work; quote values that contain spaces.
  118. - An invalid value is reported and the previous good configuration is kept, so
  119. a typo will not abort the loop.
  120. - The file is sourced as plain shell variables (not exported), so the shell
  121. environment is never a configuration channel. `RALPH_LOCAL_DIR` (the
  122. script-managed `.ralph` directory) is the only exported variable and cannot
  123. be moved by the file.
  124. ## Stopping the loop
  125. Create a `stop.md` file to stop before the next iteration:
  126. - `stop.md` in the invocation directory, or
  127. - any `stop.md` anywhere inside the `plan/` subtree.
  128. The script checks for it before each iteration and exits cleanly without
  129. deleting the file. If a matching `stop.md` already exists at startup, the loop
  130. exits immediately. This lets the agent itself signal "I'm done" by creating
  131. the file as part of its work.
  132. ## Auto-switching agent on token exhaustion
  133. When an iteration exits non-zero, the loop can detect that the current agent ran
  134. out of tokens (usage/quota/credits or rate limit) and switch to a different
  135. agent automatically. This is on by default (`RALPH_SWITCH_ON_EXHAUSTION=true`).
  136. ### Agent rotation
  137. Switching follows a fixed cycle, where each agent's successor is both the
  138. detector consulted on failure and the agent switched to:
  139. ```
  140. codex → claude → gemini → devin → codex
  141. ```
  142. | Failed agent | Detector / next agent |
  143. | --- | --- |
  144. | `codex` | `claude` |
  145. | `claude` | `gemini` |
  146. | `gemini` | `devin` |
  147. | `devin` | `codex` |
  148. The successor is always a different agent from the one that failed. Because each
  149. exhaustion advances one step, repeated token exhaustion walks the full cycle
  150. (e.g. `codex` exhausted → `claude`; if `claude` later exhausts → `gemini`, and
  151. so on, wrapping back to `codex`).
  152. ### How it works
  153. 1. After a non-zero iteration, the **next agent in the rotation** is launched as
  154. a cheap, low-capability "detector". It reads the tail of the failed
  155. iteration's log.
  156. 2. The detector answers a single structured line — `TOKENS_EXHAUSTED=true` or
  157. `TOKENS_EXHAUSTED=false`.
  158. 3. If `true`, `RALPH_TOOL` is rewritten in `.ralph/.env` to that next agent, so
  159. the **next iteration** runs with it (the failed iteration is not retried). If
  160. `false`, nothing changes.
  161. If the next agent's CLI is not installed, the check is skipped and no switch
  162. happens. The whole detection (detector agent, its output, and the decision) is
  163. appended to the iteration's log. Set `RALPH_SWITCH_ON_EXHAUSTION=false` to
  164. disable.
  165. ## Hard RAM limit
  166. Agents can leak or balloon in memory over long autonomous runs. `RALPH_MEMORY_MAX`
  167. (default `8G`) caps the RAM available to the agent process. The limit is enforced
  168. by the Linux kernel: each iteration runs the agent inside a transient systemd
  169. user scope created with
  170. ```
  171. systemd-run --user --scope -p MemoryMax=<RALPH_MEMORY_MAX> -p MemorySwapMax=0 -- <agent>
  172. ```
  173. `MemorySwapMax=0` keeps the cap on real RAM rather than letting it spill to swap.
  174. If the agent exceeds the limit it is **OOM-killed**, the iteration exits non-zero
  175. (and is then subject to the usual exhaustion check / agent switch). The value
  176. accepts any systemd memory format (`8G`, `512M`, raw bytes, or a percentage of
  177. total RAM); set it empty to disable the limit.
  178. If `systemd-run` user scopes are not available on the host, the agent runs
  179. **without** a limit and a one-time warning is printed.
  180. ## Skills
  181. This repo also distributes the skills that ralph itself relies on, so they
  182. travel with the project instead of living only under `~/.claude` / `~/.codex`.
  183. The same approach as
  184. [`rolemaster`](https://gitlab.com/gallego.cesar/rolemaster): the source of truth
  185. is `skills/<name>/SKILL.md`, and `just` recipes copy them into each tool's
  186. user-level skills directory.
  187. | Skill | What it does |
  188. |-------|--------------|
  189. | `juez` | Independent reviewer of `plan/task/*.md`: inserts `[juez]` checkpoints, judges reproducible evidence, unblocks stuck blocks, and (only on `/juez auditar`) audits global progress in read-only mode. |
  190. | `maestro` | Curator of the project's local skills: after each task its `review` action reads the plan and loop logs and creates, extends, or deletes local skills (methodologies, pitfalls, decisions) under `skills/` so future planning and execution stop groping blindly. |
  191. ```sh
  192. just skills-install # copy all skills to Claude Code, Codex CLI, Antigravity CLI
  193. just skills-sync # re-propagate changes after editing a skill (alias of install)
  194. just skills-status # show what is installed and whether it differs
  195. just skills-uninstall # remove only the skills from this repo
  196. ```
  197. Restart Codex and Antigravity after install so they pick up new skills (Claude
  198. detects them on the next session).
  199. ## Logs
  200. Each iteration writes a timestamped log to `.ralph/logs/` containing the
  201. resolved configuration and the CLI's output. Old logs are rotated according to
  202. `RALPH_LOOP_MAX_LOGS`. The `.ralph/` directory lives in your workspace and the
  203. `logs/` subdirectory is git-ignored.
  204. ## Contributing
  205. Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for
  206. the development workflow, the **Bash ↔ PowerShell parity** rule, coding style,
  207. and the CLA process. By participating you agree to our
  208. [Code of Conduct](CODE_OF_CONDUCT.md).
  209. ## Security
  210. Please report security vulnerabilities responsibly — see
  211. [SECURITY.md](.github/SECURITY.md). Do **not** open a public issue for security
  212. reports.
  213. ## Disclaimer
  214. This software is an open source project from the **Santander AI Lab**, provided **"as is"** under its [license](LICENSE), without warranties or conditions of any kind. It is **not an official Banco Santander product or service**, carries no commitment of production support, and does not constitute financial, legal or professional advice.
  215. "Santander" and its logo are registered trademarks of **Banco Santander, S.A.** The project license does not grant any right to use them beyond factual attribution.
  216. If you believe you have found a security vulnerability, follow our [security policy](https://github.com/SantanderAI/.github/blob/main/SECURITY.md) — do not open a public issue. You are responsible for assessing the suitability of this software for your use case and for keeping your own deployments up to date.
  217. ## License
  218. Licensed under the [Apache License 2.0](LICENSE). Copyright (c) 2026 César
  219. Gallego Rodríguez — see [NOTICE](NOTICE) for attribution. `ralph` was originally
  220. created by César Gallego Rodríguez ([original repository on
  221. GitLab](https://gitlab.com/gallego.cesar/ralph)) and is published as open source
  222. by Santander AI Lab with the author's consent.
  223. ## Citation
  224. If you use `ralph` in your work, please cite it using the metadata in
  225. [CITATION.cff](CITATION.cff).

Ratings and comments

Sign in to rate this skill.

Sign in

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