README
¶
Ralph
--. .-+.
-+++--. .-+++#.
+++++++-. .-+++++++-
+++++++++-. ..... .+++++++++-
+++++++++++-++++++--++++++++++-
++++++++++++++++++++++++++++++-
+++++++++++++++++++----+++++++-
-++++++++++++++++++. ..--+++.
.+++++-...--+++++++ ...-+-
-+++- ..---++... ...+.
.++++. +#+ -++.+#+ ...--
-++++.. -++.-++-+#-...-+.
-++++- .###- .-++.
.-+. . .+
.+-. --. ...
.++++ ..-+-. ..
.++++ ...-.-+--.
.++++-. +#+-..-----
-+++++++--######++-- .
... -++++---++#####+++-+-.
.. .-. -++++. ...-+--...
. .-++--..+++++-.. ...-+++-
... .-+++++-+++++++----+++++.
...++++++++++++--....--+++-
.-+++++++++++- .++.
.......-----##+..........+##-.....
........................
A small, opinionated Go CLI that drives an iterative loop against the 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.
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
<promise>...</promise>; Ralph emits an event when it sees one. - Hard limits.
--max-iterationsand--timeoutkeep runaway loops in check. - No magic. Plain CLI, plain logs, no TUI, no wizard.
Install
Requires Go 1.25+ and the GitHub Copilot CLI
on $PATH.
# 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
# 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 <promise>...</promise> 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 <promise>. |
--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
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
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. Contribution workflow is in CONTRIBUTING.md. User-visible changes belong in CHANGELOG.md. Security disclosures go through SECURITY.md.
Acknowledgements
- The original Ralph Wiggum plugin for Claude Code that inspired the loop pattern.
- The GitHub Copilot SDK team.
- Charmbracelet for
lipgloss.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
ralph
command
Package main is the entry point for the Ralph CLI application.
|
Package main is the entry point for the Ralph CLI application. |
|
internal
|
|
|
cli
Package cli implements the command-line interface for Ralph using Cobra.
|
Package cli implements the command-line interface for Ralph using Cobra. |
|
core
Package core provides the loop engine execution logic.
|
Package core provides the loop engine execution logic. |
|
sdk
Package sdk provides a wrapper around the GitHub Copilot SDK.
|
Package sdk provides a wrapper around the GitHub Copilot SDK. |
|
tui/styles
Package styles provides Lip Gloss styling for TUI components.
|
Package styles provides Lip Gloss styling for TUI components. |
|
pkg
|
|
|
version
Package version provides version information for Ralph.
|
Package version provides version information for Ralph. |