@pi-unipi/ralph 0.1.10 → 0.1.11
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 +28 -34
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,19 +1,8 @@
|
|
|
1
1
|
# @pi-unipi/ralph
|
|
2
2
|
|
|
3
|
-
Long-running iterative
|
|
3
|
+
Long-running iterative loops that persist across sessions. Start a loop, the agent works through tasks, calls `ralph_done` after each step, and reflects periodically. If the session crashes or you close Pi, the loop resumes where it left off.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
## Install
|
|
8
|
-
|
|
9
|
-
```bash
|
|
10
|
-
pi install npm:@pi-unipi/ralph
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
Or as part of the full suite:
|
|
14
|
-
```bash
|
|
15
|
-
pi install npm:unipi
|
|
16
|
-
```
|
|
5
|
+
Ralph is for work that takes more than one pass — migrating a codebase, implementing a multi-step feature, or processing a backlog. The agent iterates until the task is done or it hits the iteration limit.
|
|
17
6
|
|
|
18
7
|
## Commands
|
|
19
8
|
|
|
@@ -37,28 +26,24 @@ pi install npm:unipi
|
|
|
37
26
|
| `--items-per-iteration N` | Suggest N items per turn (prompt hint) |
|
|
38
27
|
| `--reflect-every N` | Reflect every N iterations |
|
|
39
28
|
|
|
40
|
-
##
|
|
29
|
+
## Special Triggers
|
|
41
30
|
|
|
42
|
-
|
|
43
|
-
|------|-------------|
|
|
44
|
-
| `ralph_start` | Start a ralph loop (called by agent) |
|
|
45
|
-
| `ralph_done` | Signal iteration complete (called by agent) |
|
|
31
|
+
The workflow `work` skill detects ralph and encourages loops when a plan has 3 or more subtasks. Instead of executing everything in one pass, the agent starts a ralph loop and iterates through the checklist.
|
|
46
32
|
|
|
47
|
-
|
|
33
|
+
Ralph registers with the info-screen dashboard, showing active loops, total iterations, and loop status. The footer package subscribes to `RALPH_LOOP_START`, `RALPH_LOOP_END`, and `RALPH_ITERATION_DONE` events to display loop stats in the status bar.
|
|
48
34
|
|
|
49
|
-
|
|
50
|
-
2. **Iterate** — agent works on task, updates progress, calls `ralph_done`
|
|
51
|
-
3. **Reflect** — optional reflection prompts at configurable intervals
|
|
52
|
-
4. **Complete** — agent emits `COMPLETE` marker or max iterations reached
|
|
53
|
-
5. **Persist** — state saved to disk, survives session restarts
|
|
35
|
+
## How the Agent Uses Ralph
|
|
54
36
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
37
|
+
1. Agent calls `ralph_start` with a task description and checklist
|
|
38
|
+
2. Ralph creates a task file in `.unipi/ralph/` and begins the loop
|
|
39
|
+
3. Agent works on the first checklist item, then calls `ralph_done`
|
|
40
|
+
4. Ralph marks the item complete and returns the next iteration
|
|
41
|
+
5. At reflection intervals, the agent pauses to review progress
|
|
42
|
+
6. When all items are done (or max iterations reached), the loop ends
|
|
43
|
+
|
|
44
|
+
The `ralph_done` tool signals completion of one iteration. The agent decides what to do each iteration — ralph just tracks progress and persists state.
|
|
60
45
|
|
|
61
|
-
|
|
46
|
+
### Task File Format
|
|
62
47
|
|
|
63
48
|
Loops operate on markdown task files:
|
|
64
49
|
|
|
@@ -81,6 +66,18 @@ Redesign the authentication system.
|
|
|
81
66
|
Session 1: Completed token rotation design.
|
|
82
67
|
```
|
|
83
68
|
|
|
69
|
+
## Configurables
|
|
70
|
+
|
|
71
|
+
Loop behavior is controlled per-invocation via flags:
|
|
72
|
+
|
|
73
|
+
| Setting | Default | What It Does |
|
|
74
|
+
|---------|---------|--------------|
|
|
75
|
+
| `max-iterations` | 50 | Hard stop after N iterations |
|
|
76
|
+
| `items-per-iteration` | 3 | Hint for how many checklist items per pass |
|
|
77
|
+
| `reflect-every` | 5 | Iterations between reflection prompts |
|
|
78
|
+
|
|
79
|
+
These are set when starting a loop, not in a config file. Each loop can have different settings.
|
|
80
|
+
|
|
84
81
|
## State Storage
|
|
85
82
|
|
|
86
83
|
```
|
|
@@ -91,10 +88,7 @@ Session 1: Completed token rotation design.
|
|
|
91
88
|
└── loop-name.* ← archived loops
|
|
92
89
|
```
|
|
93
90
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
- **@pi-unipi/core** — event types, constants, utilities
|
|
97
|
-
- **@pi-unipi/info-screen** — registers info group showing loop status
|
|
91
|
+
State persists across sessions. Close Pi, reopen, resume the loop — it picks up where it left off.
|
|
98
92
|
|
|
99
93
|
## License
|
|
100
94
|
|