@pi-unipi/ralph 0.1.1 → 0.1.3
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 +101 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# @pi-unipi/ralph
|
|
2
|
+
|
|
3
|
+
Long-running iterative development loops for [Pi coding agent](https://github.com/badlogic/pi-mono).
|
|
4
|
+
|
|
5
|
+
Start a loop, the agent works through iterations, reflects periodically, and completes when done. State persists across sessions.
|
|
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
|
+
```
|
|
17
|
+
|
|
18
|
+
## Commands
|
|
19
|
+
|
|
20
|
+
| Command | Description |
|
|
21
|
+
|---------|-------------|
|
|
22
|
+
| `/unipi:ralph start <name\|path>` | Start a new loop |
|
|
23
|
+
| `/unipi:ralph stop` | Pause current loop |
|
|
24
|
+
| `/unipi:ralph resume <name>` | Resume a paused loop |
|
|
25
|
+
| `/unipi:ralph status` | Show all loops |
|
|
26
|
+
| `/unipi:ralph cancel <name>` | Delete loop state |
|
|
27
|
+
| `/unipi:ralph archive <name>` | Move loop to archive |
|
|
28
|
+
| `/unipi:ralph clean [--all]` | Clean completed loops |
|
|
29
|
+
| `/unipi:ralph list --archived` | Show archived loops |
|
|
30
|
+
| `/unipi:ralph nuke [--yes]` | Delete all ralph data |
|
|
31
|
+
|
|
32
|
+
### Options
|
|
33
|
+
|
|
34
|
+
| Flag | Description |
|
|
35
|
+
|------|-------------|
|
|
36
|
+
| `--max-iterations N` | Stop after N iterations (default: 50) |
|
|
37
|
+
| `--items-per-iteration N` | Suggest N items per turn (prompt hint) |
|
|
38
|
+
| `--reflect-every N` | Reflect every N iterations |
|
|
39
|
+
|
|
40
|
+
## Tools
|
|
41
|
+
|
|
42
|
+
| Tool | Description |
|
|
43
|
+
|------|-------------|
|
|
44
|
+
| `ralph_start` | Start a ralph loop (called by agent) |
|
|
45
|
+
| `ralph_done` | Signal iteration complete (called by agent) |
|
|
46
|
+
|
|
47
|
+
## How It Works
|
|
48
|
+
|
|
49
|
+
1. **Start** — creates a task file in `.unipi/ralph/` and begins iteration loop
|
|
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
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
start → iterate → done → iterate → ... → complete
|
|
57
|
+
↑ │
|
|
58
|
+
└──── resume ────────────────────────────┘
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Task File Format
|
|
62
|
+
|
|
63
|
+
Loops operate on markdown task files:
|
|
64
|
+
|
|
65
|
+
```markdown
|
|
66
|
+
# Task
|
|
67
|
+
|
|
68
|
+
Redesign the authentication system.
|
|
69
|
+
|
|
70
|
+
## Goals
|
|
71
|
+
- Migrate to JWT refresh tokens
|
|
72
|
+
- Add role-based access control
|
|
73
|
+
|
|
74
|
+
## Checklist
|
|
75
|
+
- [x] Design token rotation
|
|
76
|
+
- [ ] Implement refresh endpoint
|
|
77
|
+
- [ ] Add RBAC middleware
|
|
78
|
+
- [ ] Write tests
|
|
79
|
+
|
|
80
|
+
## Notes
|
|
81
|
+
Session 1: Completed token rotation design.
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## State Storage
|
|
85
|
+
|
|
86
|
+
```
|
|
87
|
+
.unipi/ralph/
|
|
88
|
+
├── loop-name.state.json ← active/paused state
|
|
89
|
+
├── loop-name.md ← task file
|
|
90
|
+
└── archive/
|
|
91
|
+
└── loop-name.* ← archived loops
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## Integration
|
|
95
|
+
|
|
96
|
+
- **@pi-unipi/core** — event types, constants, utilities
|
|
97
|
+
- **@pi-unipi/info-screen** — registers info group showing loop status
|
|
98
|
+
|
|
99
|
+
## License
|
|
100
|
+
|
|
101
|
+
MIT
|