|
| 1 | +# FAQ |
| 2 | + |
| 3 | +Common questions about ralphify. For setup problems and error messages, see [Troubleshooting](troubleshooting.md). |
| 4 | + |
| 5 | +## General |
| 6 | + |
| 7 | +### What is the Ralph Wiggum technique? |
| 8 | + |
| 9 | +It's named after the Simpsons character who bumbles through situations but eventually gets things done. The idea: put an AI coding agent in a loop, let it make one change per iteration, and add "signs" to the prompt when it does something wrong — like posting "SLIDE DOWN, DON'T JUMP" next to a slide. The agent doesn't need to remember past mistakes because the signs are always there in the prompt. |
| 10 | + |
| 11 | +Read the original essay: [Ralph Wiggum as a "software engineer"](https://ghuntley.com/ralph/) |
| 12 | + |
| 13 | +### Does ralphify work with agents other than Claude Code? |
| 14 | + |
| 15 | +Yes. Ralphify works with any CLI that reads a prompt from **stdin** and exits when done. Change the `command` and `args` in `ralph.toml`: |
| 16 | + |
| 17 | +```toml |
| 18 | +# Example: custom wrapper script |
| 19 | +[agent] |
| 20 | +command = "bash" |
| 21 | +args = ["-c", "cat - | my-agent-wrapper --non-interactive"] |
| 22 | +prompt = "PROMPT.md" |
| 23 | +``` |
| 24 | + |
| 25 | +Claude Code is the default because its `-p` flag is designed for exactly this use case — reading a prompt from stdin and running non-interactively. |
| 26 | + |
| 27 | +### Does this cost money? |
| 28 | + |
| 29 | +Ralphify itself is free and open source (MIT license). But the AI agent it runs will use API credits or a subscription. Each iteration is one agent session, so costs scale with the number of iterations and the amount of work per iteration. |
| 30 | + |
| 31 | +**Tips to control costs:** |
| 32 | + |
| 33 | +- Start with `ralph run -n 3` to test before running indefinitely |
| 34 | +- Use `--timeout` to kill runaway iterations |
| 35 | +- Write focused prompts that keep iterations short and targeted |
| 36 | + |
| 37 | +### What are the requirements? |
| 38 | + |
| 39 | +- Python 3.11+ |
| 40 | +- An AI coding agent CLI that accepts piped input (e.g. [Claude Code](https://docs.anthropic.com/en/docs/claude-code)) |
| 41 | +- A git repository (recommended but not strictly required) |
| 42 | + |
| 43 | +### Can I use this in CI/CD? |
| 44 | + |
| 45 | +Yes. Ralphify is a standard CLI tool that runs anywhere Python 3.11+ is available: |
| 46 | + |
| 47 | +```bash |
| 48 | +pip install ralphify |
| 49 | +ralph run -n 5 --stop-on-error --timeout 300 --log-dir artifacts/ralph-logs |
| 50 | +``` |
| 51 | + |
| 52 | +Make sure the agent CLI is installed and authenticated in your CI environment. Use `-n` and `--stop-on-error` to keep runs bounded. |
| 53 | + |
| 54 | +## Usage |
| 55 | + |
| 56 | +### Can I edit the prompt while the loop is running? |
| 57 | + |
| 58 | +Yes — this is a core feature. `PROMPT.md` is re-read from disk at the start of every iteration. Edit it, save, and the next iteration uses the updated version. This is the main way to steer the agent in real time. |
| 59 | + |
| 60 | +### What happens if the agent doesn't commit? |
| 61 | + |
| 62 | +Nothing breaks — ralphify doesn't require or enforce commits. But uncommitted changes accumulate and may confuse the agent in later iterations (it might redo work or create conflicts). Best practice is to include explicit commit instructions in your prompt. |
| 63 | + |
| 64 | +### How many iterations should I run? |
| 65 | + |
| 66 | +Start small with `-n 3` or `-n 5` to verify the agent is producing useful work. Review the output, tune the prompt, then gradually increase. There's no universal "right" number — it depends on the size of your task and how reliable the loop is. |
| 67 | + |
| 68 | +### Does `--stop-on-error` stop on timeouts too? |
| 69 | + |
| 70 | +Yes. `--stop-on-error` stops the loop when the agent exits with a non-zero code **or** when an iteration times out (if `--timeout` is set). |
| 71 | + |
| 72 | +### What if a check always fails? |
| 73 | + |
| 74 | +This usually means the check command itself doesn't work, not that the agent is failing. Run the command manually to verify: |
| 75 | + |
| 76 | +```bash |
| 77 | +# See what's configured |
| 78 | +cat .ralph/checks/my-check/CHECK.md |
| 79 | + |
| 80 | +# Run the command directly |
| 81 | +uv run pytest -x # or whatever the command is |
| 82 | +``` |
| 83 | + |
| 84 | +If it fails outside of ralphify, fix the underlying issue first. If it only fails after the agent runs, make the failure instruction more specific about how to fix it. |
| 85 | + |
| 86 | +### Can I run multiple loops in parallel? |
| 87 | + |
| 88 | +Yes, but they should work on **separate branches** to avoid git conflicts: |
| 89 | + |
| 90 | +```bash |
| 91 | +# Terminal 1 |
| 92 | +git checkout -b feature-a && ralph run |
| 93 | + |
| 94 | +# Terminal 2 |
| 95 | +git checkout -b feature-b && ralph run |
| 96 | +``` |
| 97 | + |
| 98 | +Each loop operates independently with its own prompt and checks. |
| 99 | + |
| 100 | +### How do I limit API costs? |
| 101 | + |
| 102 | +| Strategy | How | |
| 103 | +|---|---| |
| 104 | +| Cap iterations | `ralph run -n 10` | |
| 105 | +| Kill stuck runs | `ralph run --timeout 300` | |
| 106 | +| Stop on failure | `ralph run --stop-on-error` | |
| 107 | +| Write focused prompts | One clear task per iteration, not "improve everything" | |
| 108 | +| Review before scaling | Always start with `-n 3` and check the logs | |
| 109 | + |
| 110 | +## Configuration |
| 111 | + |
| 112 | +### Should I commit the `.ralph/` directory? |
| 113 | + |
| 114 | +Yes. It contains your checks, contexts, and instructions — this is project configuration that your team should share: |
| 115 | + |
| 116 | +```bash |
| 117 | +git add .ralph/ |
| 118 | +git commit -m "chore: add ralph checks and contexts" |
| 119 | +``` |
| 120 | + |
| 121 | +### What's the difference between instructions and just writing rules in PROMPT.md? |
| 122 | + |
| 123 | +Instructions are **modular** — you can enable, disable, or swap them without editing the prompt. This is useful when: |
| 124 | + |
| 125 | +- Multiple prompts share the same coding standards |
| 126 | +- You want to temporarily disable a rule without deleting it |
| 127 | +- Team members maintain different instruction sets |
| 128 | + |
| 129 | +If you have one prompt with a few simple rules, writing them directly in `PROMPT.md` is simpler and easier to maintain. |
| 130 | + |
| 131 | +### Can I use a different prompt file name? |
| 132 | + |
| 133 | +Yes. Change the `prompt` field in `ralph.toml`: |
| 134 | + |
| 135 | +```toml |
| 136 | +[agent] |
| 137 | +command = "claude" |
| 138 | +args = ["-p", "--dangerously-skip-permissions"] |
| 139 | +prompt = "my-custom-prompt.md" |
| 140 | +``` |
| 141 | + |
| 142 | +The file can be named anything and placed anywhere relative to the project root. |
| 143 | + |
| 144 | +### What's the difference between a check `command` and a `run.*` script? |
| 145 | + |
| 146 | +A `command` in the CHECK.md frontmatter is a single shell command. A `run.*` script (e.g. `run.sh`, `run.py`) in the check directory is an executable file that can contain multi-step logic. |
| 147 | + |
| 148 | +Use a **command** for simple, one-line validations: |
| 149 | + |
| 150 | +```yaml |
| 151 | +command: uv run pytest -x |
| 152 | +``` |
| 153 | +
|
| 154 | +Use a **script** when you need setup/teardown, multiple steps, or conditional logic: |
| 155 | +
|
| 156 | +```bash |
| 157 | +#!/bin/bash |
| 158 | +# .ralph/checks/integration/run.sh |
| 159 | +set -e |
| 160 | +docker compose up -d |
| 161 | +pytest tests/integration/ |
| 162 | +docker compose down |
| 163 | +``` |
| 164 | + |
| 165 | +If both exist, the script takes precedence. See [Primitives](primitives.md#using-a-script-instead-of-a-command) for details. |
0 commit comments