https://github.com/patbaumgartner/copilot-ralph
Iterative AI development loop CLI built on the GitHub Copilot SDK
https://github.com/patbaumgartner/copilot-ralph
Last synced: about 2 months ago
JSON representation
Iterative AI development loop CLI built on the GitHub Copilot SDK
- Host: GitHub
- URL: https://github.com/patbaumgartner/copilot-ralph
- Owner: patbaumgartner
- License: mit
- Created: 2026-04-26T20:24:34.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-26T21:34:14.000Z (about 2 months ago)
- Last Synced: 2026-04-26T22:21:42.252Z (about 2 months ago)
- Language: Go
- Size: 152 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Ralph
```text
--. .-+.
-+++--. .-+++#.
+++++++-. .-+++++++-
+++++++++-. ..... .+++++++++-
+++++++++++-++++++--++++++++++-
++++++++++++++++++++++++++++++-
+++++++++++++++++++----+++++++-
-++++++++++++++++++. ..--+++.
.+++++-...--+++++++ ...-+-
-+++- ..---++... ...+.
.++++. +#+ -++.+#+ ...--
-++++.. -++.-++-+#-...-+.
-++++- .###- .-++.
.-+. . .+
.+-. --. ...
.++++ ..-+-. ..
.++++ ...-.-+--.
.++++-. +#+-..-----
-+++++++--######++-- .
... -++++---++#####+++-+-.
.. .-. -++++. ...-+--...
. .-++--..+++++-.. ...-+++-
... .-+++++-+++++++----+++++.
...++++++++++++--....--+++-
.-+++++++++++- .++.
.......-----##+..........+##-.....
........................
```
> A small, opinionated Go CLI that drives an iterative loop against the
> [GitHub Copilot SDK](https://github.com/github/copilot-sdk). One prompt
> in, many turns of progress out — until Ralph decides he's done, you run
> out of iterations, or you hit `Ctrl+C`.
[](https://github.com/patbaumgartner/copilot-ralph/actions/workflows/ci.yml)
[](https://github.com/patbaumgartner/copilot-ralph/actions/workflows/release.yml)
[](https://pkg.go.dev/github.com/patbaumgartner/copilot-ralph)
[](LICENSE)
## Why Ralph
The "Ralph Wiggum" technique is dead simple: keep poking the model with the
same prompt until the work is actually done. Ralph wraps that idea in a
single binary so you can hand a task to Copilot and watch it iterate
without babysitting the chat window.
- **Stream first.** Tokens, reasoning, and tool calls land on stdout the
moment they arrive.
- **Promise-based completion.** The model wraps its sign-off in
`...`; Ralph emits an event when it sees one.
- **Hard limits.** `--max-iterations` and `--timeout` keep runaway loops
in check.
- **No magic.** Plain CLI, plain logs, no TUI, no wizard.
## Install
Requires Go 1.25+ and the [GitHub Copilot CLI](https://github.com/github/copilot)
on `$PATH`.
```bash
# Install the latest release directly
go install github.com/patbaumgartner/copilot-ralph/cmd/ralph@latest
# Or grab a binary from the Releases page
# https://github.com/patbaumgartner/copilot-ralph/releases
# Or build from source
git clone https://github.com/patbaumgartner/copilot-ralph.git
cd copilot-ralph
make build # produces ./bin/ralph
```
## Usage
```bash
# Inline prompt
ralph run "Add unit tests for the parser module"
# Markdown file as prompt
ralph run task.md
# Cap iterations and runtime
ralph run --max-iterations 5 --timeout 10m "Refactor authentication"
# Show the resolved config without calling the model
ralph run --dry-run "Implement OAuth"
# Custom system prompt (note: --system-prompt-mode=replace removes Ralph's
# built-in ... instruction)
ralph run \
--system-prompt prompts/expert-go.md \
--system-prompt-mode replace \
"Optimise the hot path"
```
### Useful flags
| Flag | Default | Purpose |
| ----------------------------- | ------------- | --------------------------------------------- |
| `-m`, `--max-iterations` | `10` | Stop after N loops. |
| `-t`, `--timeout` | `30m` | Stop after this duration. |
| `--promise` | `I'm special!`| Phrase the model wraps in ``. |
| `--model` | `gpt-4` | Copilot model id. |
| `--working-dir` | cwd | Where the assistant runs tools. |
| `--log-level` | `info` | `debug` / `info` / `warn` / `error`. |
| `--streaming` | `true` | Stream deltas vs. wait for full messages. |
| `--system-prompt` | (built-in) | Inline text or path to a Markdown file. |
| `--system-prompt-mode` | `append` | `append` or `replace` Ralph's system prompt. |
| `--dry-run` | `false` | Print the config and exit. |
`ralph version` prints build metadata. `ralph --help` lists everything.
## How it works
```text
prompt ──► Copilot SDK ──► assistant tokens, tool calls
▲ │
└──── next iteration ──┘
(until promise / max-iterations / timeout / Ctrl+C)
```
The loop lives in `internal/core`. The SDK wrapper (`internal/sdk`) handles
sessions, retries, and translates SDK events into Ralph-flavoured events.
The CLI layer (`cmd/ralph`, `internal/cli`) wires flags to a `LoopConfig`
and prints events as they stream in. There is no shared mutable state
beyond Cobra flag bindings.
## Exit codes
| Code | Meaning |
| ---- | ---------------------------------------------- |
| `0` | Loop finished cleanly (max iterations or done).|
| `1` | Generic failure / SDK error. |
| `2` | Invalid configuration or arguments. |
| `3` | `--timeout` exceeded. |
| `130`| Cancelled with `Ctrl+C`. |
## Development
```bash
make all # tidy + fmt + vet + lint + test + build
make test # go test -race -cover ./...
make build # ./bin/ralph
```
Conventions, architecture, and "how to add X" live in [AGENTS.md](./AGENTS.md).
Contribution workflow is in [CONTRIBUTING.md](./CONTRIBUTING.md). User-visible
changes belong in [CHANGELOG.md](./CHANGELOG.md). Security disclosures go
through [SECURITY.md](./SECURITY.md).
## Acknowledgements
- The original [Ralph Wiggum plugin](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum)
for Claude Code that inspired the loop pattern.
- The [GitHub Copilot SDK](https://github.com/github/copilot-sdk) team.
- [Charmbracelet](https://github.com/charmbracelet) for `lipgloss`.
## License
[MIT](./LICENSE)