@herbcaudill/ralph 1.0.2 → 1.1.0
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 +93 -0
- package/dist/index.js +215 -136
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
- package/templates/core-prompt.md +0 -16
- package/templates/skills/manage-tasks/SKILL.md +0 -3
- package/templates/workflow.md +4 -18
package/README.md
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# @herbcaudill/ralph
|
|
2
|
+
|
|
3
|
+
Autonomous AI session engine that wraps the Claude CLI to run iterative development workflows. Spawns Claude CLI processes with a custom prompt, captures streaming JSON output, displays it in a formatted terminal UI using Ink, and orchestrates multiple sessions.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install -g @herbcaudill/ralph
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Quick start
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
# Initialize ralph in your project
|
|
15
|
+
ralph init
|
|
16
|
+
|
|
17
|
+
# Run autonomous sessions
|
|
18
|
+
ralph
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Usage
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
ralph [sessions] Run N autonomous sessions (default: auto-calculated)
|
|
25
|
+
ralph init Set up .ralph/ directory with workflow config
|
|
26
|
+
ralph --replay Replay events from the most recent log file
|
|
27
|
+
ralph --replay <f> Replay events from a specific file
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
### Options
|
|
31
|
+
|
|
32
|
+
| Flag | Description |
|
|
33
|
+
| ---------------------- | ------------------------------------------------------ |
|
|
34
|
+
| `--watch`, `-w` | After completing all tasks, watch for new beads issues |
|
|
35
|
+
| `--json`, `-j` | Output events as JSON (machine-readable mode) |
|
|
36
|
+
| `--agent <name>`, `-a` | Agent to use: `claude` (default) or `codex` |
|
|
37
|
+
| `--replay [file]` | Replay events from a log file |
|
|
38
|
+
|
|
39
|
+
### Session count
|
|
40
|
+
|
|
41
|
+
By default, Ralph runs `ceil(openIssues * 1.2)` sessions, bounded between 10 and 100. Pass a number to override: `ralph 5`.
|
|
42
|
+
|
|
43
|
+
## How it works
|
|
44
|
+
|
|
45
|
+
1. Ralph combines a core prompt with your repo's `.ralph/workflow.md` to build the session instructions
|
|
46
|
+
2. Spawns the agent CLI with `--output-format stream-json`
|
|
47
|
+
3. The agent checks build/tests, finds available issues via `bd ready`, claims one, completes it, and closes it
|
|
48
|
+
4. Events are streamed to the terminal UI and logged to `.ralph/events-*.jsonl`
|
|
49
|
+
5. Sessions repeat until all issues are done or the session limit is reached
|
|
50
|
+
|
|
51
|
+
## Runtime controls
|
|
52
|
+
|
|
53
|
+
| Key | Action |
|
|
54
|
+
| -------- | --------------------------- |
|
|
55
|
+
| `Escape` | Send a message to the agent |
|
|
56
|
+
| `Ctrl+T` | Add a todo item |
|
|
57
|
+
| `Ctrl+S` | Stop after current session |
|
|
58
|
+
| `Ctrl+P` | Pause/resume |
|
|
59
|
+
|
|
60
|
+
### JSON mode stdin commands
|
|
61
|
+
|
|
62
|
+
```json
|
|
63
|
+
{ "type": "message", "text": "your message" }
|
|
64
|
+
{ "type": "stop" }
|
|
65
|
+
{ "type": "pause" }
|
|
66
|
+
{ "type": "resume" }
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Configuration
|
|
70
|
+
|
|
71
|
+
After `ralph init`, customize `.ralph/workflow.md` with your repo's build commands, test commands, and task prioritization rules.
|
|
72
|
+
|
|
73
|
+
## Template system
|
|
74
|
+
|
|
75
|
+
- **Core prompt** (bundled) - Session lifecycle, task assignment, output tokens
|
|
76
|
+
- **Workflow** (`.ralph/workflow.md`) - Repo-specific build/test commands and workflow rules
|
|
77
|
+
|
|
78
|
+
## Environment variables
|
|
79
|
+
|
|
80
|
+
| Variable | Description |
|
|
81
|
+
| ------------------- | -------------------------------------------------------------------- |
|
|
82
|
+
| `ANTHROPIC_API_KEY` | Required for the Claude agent |
|
|
83
|
+
| `OPENAI_API_KEY` | Optional for the Codex agent |
|
|
84
|
+
| `RALPH_DEBUG` | Enable debug logging (`1`, or namespace like `messagequeue,session`) |
|
|
85
|
+
| `RALPH_CWD` | Override base path for relative path rendering |
|
|
86
|
+
|
|
87
|
+
## Debug logging
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
RALPH_DEBUG=1 ralph # all debug output
|
|
91
|
+
RALPH_DEBUG=messagequeue ralph # specific namespace
|
|
92
|
+
RALPH_DEBUG=messagequeue,session ralph # multiple namespaces
|
|
93
|
+
```
|