@wavilikhin/ralph-wiggum 0.1.0 → 0.1.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +46 -5
- package/package.json +5 -2
package/README.md
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# Ralph Wiggum
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@wavilikhin/ralph-wiggum)
|
|
4
|
+
[](https://github.com/wavilikhin/ralph-wiggum/actions/workflows/publish.yml)
|
|
4
5
|
|
|
5
6
|
```
|
|
6
7
|
____ _ _ __ ___
|
|
@@ -11,11 +12,47 @@ Autonomous coding loop for [OpenCode](https://opencode.ai). One task, one commit
|
|
|
11
12
|
|_| |___/
|
|
12
13
|
```
|
|
13
14
|
|
|
15
|
+
## Installation
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
# npm
|
|
19
|
+
npx @wavilikhin/ralph-wiggum init
|
|
20
|
+
|
|
21
|
+
# bun
|
|
22
|
+
bunx @wavilikhin/ralph-wiggum init
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Or install globally:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
# npm
|
|
29
|
+
npm install -g @wavilikhin/ralph-wiggum
|
|
30
|
+
|
|
31
|
+
# bun
|
|
32
|
+
bun install -g @wavilikhin/ralph-wiggum
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
This is a near-vanilla implementation of the [Ralph Wiggum autonomous loop](https://ghuntley.com/ralph/) pattern by Geoffrey Huntley. The core idea: run an AI coding agent in a loop where each iteration gets fresh context, picks exactly one task, implements it, validates it passes all checks, commits, and repeats until done. This produces clean atomic commits and avoids context window bloat.
|
|
38
|
+
|
|
39
|
+
Built for [OpenCode](https://opencode.ai), but should work with any CLI-based coding agent that can read files and run commands.
|
|
40
|
+
|
|
41
|
+
**Additions to the original pattern:**
|
|
42
|
+
- `npx` initialization that scaffolds everything into a `.ralph/` directory
|
|
43
|
+
- Structured logging with timestamps (`.ralph/logs/ralph.log`)
|
|
44
|
+
- `--verbose` flag to preserve full agent output per iteration
|
|
45
|
+
- Enforces exactly one commit per iteration (fails if zero or multiple)
|
|
46
|
+
- Verifies clean working tree after each iteration
|
|
47
|
+
- Phases-based `IMPLEMENTATION_PLAN.md` template
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
14
51
|
## What is this?
|
|
15
52
|
|
|
16
|
-
Ralph Wiggum runs
|
|
53
|
+
Ralph Wiggum runs your coding agent in a loop, where each iteration:
|
|
17
54
|
|
|
18
|
-
1. Starts with **fresh context** (new
|
|
55
|
+
1. Starts with **fresh context** (new process, no memory of previous iterations)
|
|
19
56
|
2. Picks **exactly one task** from your implementation plan
|
|
20
57
|
3. Implements it and runs **validation gates** (lint, test, build)
|
|
21
58
|
4. Creates **exactly one commit** (local only, no push)
|
|
@@ -41,7 +78,7 @@ This approach keeps context focused and produces clean, atomic commits.
|
|
|
41
78
|
|
|
42
79
|
## Prerequisites
|
|
43
80
|
|
|
44
|
-
- [OpenCode CLI](https://opencode.ai) installed and configured
|
|
81
|
+
- [OpenCode CLI](https://opencode.ai) installed and configured (or another CLI agent)
|
|
45
82
|
- Node.js 18+
|
|
46
83
|
- Git repository
|
|
47
84
|
- **AGENTS.md file in your repo root** (see below)
|
|
@@ -90,7 +127,7 @@ See [OpenCode AGENTS.md documentation](https://opencode.ai/docs/agents-md) for b
|
|
|
90
127
|
|
|
91
128
|
```bash
|
|
92
129
|
cd your-project
|
|
93
|
-
npx ralph-wiggum init
|
|
130
|
+
npx @wavilikhin/ralph-wiggum init
|
|
94
131
|
```
|
|
95
132
|
|
|
96
133
|
This creates a `.ralph/` directory with:
|
|
@@ -335,6 +372,10 @@ This often indicates the model isn't capable enough for autonomous operation. Tr
|
|
|
335
372
|
- Simplifying tasks in IMPLEMENTATION_PLAN.md
|
|
336
373
|
- Adding more context to AGENTS.md
|
|
337
374
|
|
|
375
|
+
## Credits
|
|
376
|
+
|
|
377
|
+
Based on the [Ralph Wiggum pattern](https://ghuntley.com/ralph/) by Geoffrey Huntley.
|
|
378
|
+
|
|
338
379
|
## License
|
|
339
380
|
|
|
340
381
|
MIT
|
package/package.json
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wavilikhin/ralph-wiggum",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.13",
|
|
4
4
|
"description": "Autonomous coding loop for OpenCode - one task, one commit, fresh context per iteration",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
7
|
-
"ralph-wiggum": "
|
|
7
|
+
"ralph-wiggum": "src/cli.js"
|
|
8
8
|
},
|
|
9
9
|
"files": [
|
|
10
10
|
"src/",
|
|
@@ -26,5 +26,8 @@
|
|
|
26
26
|
},
|
|
27
27
|
"engines": {
|
|
28
28
|
"node": ">=18.0.0"
|
|
29
|
+
},
|
|
30
|
+
"publishConfig": {
|
|
31
|
+
"access": "public"
|
|
29
32
|
}
|
|
30
33
|
}
|