# Open Ralph Wiggum: the prompt you send again and again until the agent prints the tag

> Open Ralph Wiggum is a TypeScript CLI that re-sends a single task prompt to Claude Code, Codex, Copilot CLI, Cursor Agent, Qwen Code or OpenCode in a loop, with the repository standing in for the memory the agent never keeps. It installs as @th0rgal/ralph-wiggum, needs Bun plus one agent CLI, and documents three of its own flags only in prose.

**Th0rgal/open-ralph-wiggum** — Type `ralph "prompt"` to start open code in a ralph loop. Also supports a prompt file & status check. Open Code, Claude Code, Codex, Copilot

- Repository: https://github.com/Th0rgal/open-ralph-wiggum
- Stars: 1,905 · Forks: 143
- Language: TypeScript
- License: MIT
- Published: 2026-10-14 · Updated: 2026-10-14 · Language: en
- Canonical page: https://hysenlabs.com/projects/th0rgal-open-ralph-wiggum

## The loop never carries context, it carries a changed directory

The mechanism is one sentence long: hand the agent the same prompt again and let the working tree stand in for the memory it does not have. Nothing travels between rounds except files. The agent starting round two knows nothing about round one except what it can read on disk, code that was written and changes sitting in git history. So an iteration that stopped halfway leaves its partial work where the next iteration trips over it, and progress becomes a property of the directory rather than of a context window.

Completion travels the same path, as text. The prompt you pass instructs the agent to print a marker such as `<promise>DONE</promise>` once the task is finished, and that printed marker is what ends the run. There is no judge process watching the output, no scheduler and no retry policy anywhere in the design. The whole feedback path is: same string in, changed files out, marker back.

## Six agent CLIs behind one flag, and no runtime dependencies

Agent choice is a single string in the command line, and the wrapper brings no agent code of its own. Six CLIs are supported, each with its own flag: `claude-code`, `codex`, `copilot`, `cursor-agent`, `qwen-code` and `opencode`, the last described as the default. The package publishes one executable, `ralph`, mapped to `bin/ralph.js`, and it declares no runtime dependency block at all. The only entry under `devDependencies` is `@types/bun` at `^1.3.5`.

That is the practical limit of the multi-agent claim. Whatever the CLI you named can see, approve and run is exactly what the loop inherits, so a missing or logged-out agent binary fails inside the first iteration rather than at install time, and ralph adds no preflight check of its own.

```bash
# Use Claude Code
ralph "Build a REST API" --agent claude-code --max-iterations 10

# Use OpenAI Codex
ralph "Create a CLI tool" --agent codex --max-iterations 10

# Use Copilot CLI
ralph "Refactor the auth module" --agent copilot --max-iterations 10
```

## Installing the ralph command, then capping the first job at five runs

Two prerequisites, then a choice of install routes. You need the Bun runtime and at least one of the agent CLIs named in the prerequisites. The path marked recommended is a global npm install:

```bash
npm install -g @th0rgal/ralph-wiggum
```

Bun users take the same package through `bun add -g`:

```bash
bun add -g @th0rgal/ralph-wiggum
```

A checkout carries its own installer, with one script per shell:

```bash
git clone https://github.com/Th0rgal/open-ralph-wiggum
cd open-ralph-wiggum
./install.sh
```

```powershell
git clone https://github.com/Th0rgal/open-ralph-wiggum
cd open-ralph-wiggum
.\install.ps1
```

Every route leaves a global `ralph` command on your PATH. Run the file-creation job from Quick Start first rather than the REST API one, since it costs seconds and tells you in a single run whether the agent binary is present, authenticated and able to write. Read the invocation shape carefully: the task text is a bare positional argument, and the ceiling is a separate flag.

```bash
ralph "Create a hello.txt file with 'Hello World'. Output <promise>DONE</promise> when complete." \
  --max-iterations 5
```

If the marker never appears, the loop still stops at the ceiling. The package is published under MIT, so anyone shipping it inside a closed product has to carry the licence text and copyright notice along.

## The bare shell loop is the real alternative, and it costs one line

The honest baseline is the technique itself, three lines of shell you can write by hand, credited in the README to Geoffrey Huntley:

```bash
# The essence of the Ralph loop:
while true; do
  claude-code "Build feature X. Output <promise>DONE</promise> when complete."  # or codex, copilot, cursor-agent, qwen, opencode
done
```

Swap the agent name and you have the same feedback loop with nothing to install. The packaged command wraps that loop with the `--agent` flag, the `--max-iterations` ceiling, a prompt file mode, a `--status` check, and the `--tasks` and `--add-context` modes. What you give up is sight of the logic itself: `ralph.ts` is the single source file behind all of it, so when the packaged behaviour disagrees with your expectation, reading that file is the only route to an answer. For a throwaway task on a machine where you already have a terminal open, the hand written loop is cheaper. For something scheduled, the global install is cheaper than maintaining your own stop condition.

## Three flags are announced twice in the file and demonstrated never

Task tracking, live monitoring and mid-loop hints each get a bullet in the feature list and a row in the benefit table, and not one code example uses them. The flags are `--tasks` for built-in task management, `--status` for a check the text says you can run from another terminal, and `--add-context` for injecting guidance without stopping the loop.

Walk every command in the file and only two flags ever appear: `--agent` and `--max-iterations`. The argument shape of the other three, then, is unknown until you open `ralph.ts`. The observability row goes a step further and promises history and struggle indicators, yet the top level listing of the checkout contains no state directory and no log file, so a reader cannot tell from the layout where that output is written. Anything the monitoring modes produce has to be recovered by reading the source code yourself.

## Two promise tags, and the stop condition is never pinned down

Quick Start shows the stop marker twice and spells it differently each time. The first example asks the agent to output `<promise>DONE</promise>` after it has created `hello.txt`. The second, for a todo REST API with tests, asks for `<promise>COMPLETE</promise>` once the tests pass. Nothing in the file states which tag the loop watches, whether either spelling is accepted, or what happens when the agent prints neither.

That gap is not cosmetic, because `--max-iterations` is the only hard limit documented anywhere in the project. A prompt whose marker disagrees with the one in the source is not rejected at startup; you discover the mismatch at the ceiling, after the agent has spent every iteration re-reading its own last attempt. The examples also expose a smaller inconsistency: the agent table lists `--agent opencode`, while the OpenCode example leaves the flag out entirely, so the default really is implicit.

## The manifest and the clone command disagree on the repository name

A close read of the install paths turns up a naming split. The clone command points at `https://github.com/Th0rgal/open-ralph-wiggum`, and that is where this repository lives. The manifest disagrees: its `repository`, `bugs` and `homepage` fields all point at `https://github.com/Th0rgal/ralph-wiggum.git`, the same path with `open-` removed, and the badges in the README read from a repository and a version feed under that shorter name too. An issue link generated from an installed copy therefore leads to a path whose name does not match the clone you typed, and neither file mentions a redirect.

The project description on the page is behind in the same way. It still leads with Open Code and names only Claude Code, Codex, Copilot and OpenCode, while the headline above the README names six agents. Pick a backend from that one line and Cursor Agent and Qwen Code, together with the `--agent cursor-agent` and `--agent qwen-code` flags, stay invisible.

## The npm tarball ships fewer files than the checkout holds

The published package is assembled from the `files` array in package.json, and it is thinner than the repository. Shipped: `bin/ralph.js`, `ralph.ts`, `completion.ts`, the two installers, the two uninstallers, `docs/ralph-omx.md`, `contrib/omx` and `scripts/test-codex-goal-mode.sh`. Left behind: `skills/`, `tests/`, `.github/`, `bun.lock` and `screenshot.webp`. So the skills directory you read on GitHub holds code that an npm user never receives, and the suite the project runs with `bun test ./tests/ralph.test.ts` cannot be executed from an installed copy at all.

Two smaller mismatches sit beside that list. `main` points at `bin/ralph.js`, a CLI entry rather than a library surface. And the build script writes a different name than the manifest installs: `bun build ralph.ts --outfile bin/ralph --compile` produces `bin/ralph`, while the bin mapping that npm installs resolves to `bin/ralph.js`. Version 1.2.2 shipped 2026-02-22, 1.3.0 followed on 2026-04-29, and 1.3.1 on 2026-05-26, which matches the version string in the manifest. The last push on record is dated 2026-06-02.

## Conclusion

Adopt ralph when the finish line is something a test can check, because the loop holds no opinion about correctness beyond the marker it asks the agent to print. Leave it alone if you need a human in the middle: --status and --tasks are named in the feature list but never shown, so the monitoring story rests on reading ralph.ts. Before wiring it into a scheduled job, check two things in the source, the exact tag that ends a run and what happens when --max-iterations is reached with no tag in sight.

## FAQ

### Does Open Ralph Wiggum need Claude Code, and which agent is the default?

No. The agent table lists six supported CLIs, and OpenCode is described as the default. The prerequisites ask for the Bun runtime plus at least one of those agent CLIs on the machine before ralph can drive it.

### How do I stop an Open Ralph Wiggum loop before it hits the iteration cap?

The prompt you pass asks the agent to print a marker, shown as <promise>DONE</promise> in one Quick Start example and <promise>COMPLETE</promise> in the other. The file does not state which of the two ends the run.

### Can I monitor a running Open Ralph Wiggum loop from a second terminal?

The feature list says --status can be checked from another terminal and shows history and struggle indicators, but no example command uses it. Only --agent and --max-iterations appear in the documented invocations.

### How do I install the ralph command on Windows?

The from-source path ships install.ps1 for PowerShell next to install.sh, so PowerShell users run .\install.ps1 after cloning. The npm route, npm install -g @th0rgal/ralph-wiggum, is the one marked recommended.

### What does Open Ralph Wiggum add over a plain shell while loop?

The hand written loop calls one agent executable with a fixed string and nothing else. The packaged command adds the --agent flag, the --max-iterations ceiling, a prompt file mode, and the --status, --tasks and --add-context modes.

## Sources

- [Issues](https://github.com/Th0rgal/open-ralph-wiggum/issues)
- [License: MIT](https://github.com/Th0rgal/open-ralph-wiggum/blob/master/LICENSE)
- [README](https://github.com/Th0rgal/open-ralph-wiggum/blob/master/README.md)
- [Releases](https://github.com/Th0rgal/open-ralph-wiggum/releases)
- [Th0rgal/open-ralph-wiggum on GitHub](https://github.com/Th0rgal/open-ralph-wiggum)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/th0rgal-open-ralph-wiggum