@herbcaudill/ralph 0.7.0 → 0.8.0

package/dist/components/EventDisplay.replay.test.js

@@ -85,24 +85,24 @@ describe("EventDisplay replay tests", () => {
       Good! The build is successful and all tests pass. Now let me check the todo list to find the
       highest-priority task.
 
-        Read .ralph/todo.md
+        Read ../.ralph/todo.md
 
       Looking at the todo list, I'll prioritize the "Inline code blocks are being put in separate
       paragraphs" issue. This is a functional bug affecting the display quality, whereas the others are
       enhancements. Let me investigate this issue first.
 
-        Read src/components/StreamingText.tsx
+        Read ../src/components/StreamingText.tsx
 
       Let me check the tests to understand the expected behavior and see if there's a failing test case:
 
-        Read src/components/StreamingText.test.tsx
+        Read ../src/components/StreamingText.test.tsx
 
       I need to understand where StreamingText is being used and what the actual problem is. Let me check
       where it's called from and look at some example output:
 
         Grep StreamingText
 
-        Read src/components/EventDisplay.tsx
+        Read ../src/components/EventDisplay.tsx
 
       I see the issue now! In EventDisplay.tsx:70, there's a <Box flexDirection="column" gap={1}> which
       wraps each StreamingText component. Each StreamingText (which represents text blocks) is being
@@ -114,7 +114,7 @@ describe("EventDisplay replay tests", () => {
 
       Let me look at how the events are being split into blocks:
 
-        Read src/components/eventToBlocks.ts
+        Read ../src/components/eventToBlocks.ts
 
       Now I understand the issue. Claude's message content can have multiple text blocks (e.g., "Here's
       the code: ", then a tool_use block, then " and that's it"). Each text block becomes a separate
@@ -124,11 +124,11 @@ describe("EventDisplay replay tests", () => {
       The fix should be to merge consecutive text blocks together. Let me write a test first to
       demonstrate the problem:
 
-        Read src/components/EventDisplay.test.tsx
+        Read ../src/components/EventDisplay.test.tsx
 
       Now let me add a test that demonstrates the inline code block problem and then fix it:
 
-        Edit src/components/EventDisplay.test.tsx
+        Edit ../src/components/EventDisplay.test.tsx
 
       Now let me run the test to confirm it fails (demonstrating the problem):
 
@@ -137,11 +137,11 @@ describe("EventDisplay replay tests", () => {
       Perfect! The test fails as expected, confirming the bug. Now I need to fix it by modifying
       eventToBlocks to merge consecutive text blocks:
 
-        Edit src/components/eventToBlocks.ts
+        Edit ../src/components/eventToBlocks.ts
 
       Now I need to also flush the text buffer at the end of the loop:
 
-        Edit src/components/eventToBlocks.ts
+        Edit ../src/components/eventToBlocks.ts
 
       Now let me run the tests again to verify the fix works:
 
@@ -150,20 +150,20 @@ describe("EventDisplay replay tests", () => {
       The test still fails. This suggests the problem might also be in EventDisplay, not just
       eventToBlocks. Let me debug by adding a simpler test to see what's happening in eventToBlocks:
 
-        Read src/components/eventToBlocks.test.ts
+        Read ../src/components/eventToBlocks.test.ts
 
       I see! The existing test "extracts multiple text blocks" expects them NOT to be merged. I need to
       update this test and add a new one specifically for consecutive text blocks:
 
-        Edit src/components/eventToBlocks.test.ts
+        Edit ../src/components/eventToBlocks.test.ts
 
       Now let me add a test for text blocks separated by tool calls:
 
-        Read src/components/eventToBlocks.test.ts
+        Read ../src/components/eventToBlocks.test.ts
 
       Let me add a test that specifically checks text blocks separated by tool calls:
 
-        Edit src/components/eventToBlocks.test.ts
+        Edit ../src/components/eventToBlocks.test.ts
 
       Now let me run all tests to verify my changes to eventToBlocks work:
 
@@ -171,12 +171,12 @@ describe("EventDisplay replay tests", () => {
 
       I need to look at this failing test:
 
-        Read src/components/eventToBlocks.test.ts
+        Read ../src/components/eventToBlocks.test.ts
 
       This test expects 3 separate IDs for 3 text blocks, but my code now merges them into 1. I need to
       update this test to reflect the new behavior:
 
-        Edit src/components/eventToBlocks.test.ts
+        Edit ../src/components/eventToBlocks.test.ts
 
       Now let me run the eventToBlocks tests again:
 
@@ -190,7 +190,7 @@ describe("EventDisplay replay tests", () => {
       rendered. The issue must be in how EventDisplay merges the events. Let me look more carefully at the
        EventDisplay logic:
 
-        Read src/components/EventDisplay.tsx
+        Read ../src/components/EventDisplay.tsx
 
       I see! The EventDisplay is doing its own deduplication, but it's NOT merging consecutive text
       blocks. The text blocks in the test data remain separate even after eventToBlocks merges them,
@@ -235,13 +235,13 @@ describe("EventDisplay replay tests", () => {
 
       That should work! Let me check if there's an issue with my implementation. Let me re-read the code:
 
-        Read src/components/eventToBlocks.ts
+        Read ../src/components/eventToBlocks.ts
 
       The code looks correct. Let me check if the EventDisplay is receiving the correct merged content. I
       think the issue might be in how EventDisplay deduplicates and merges content before calling
       eventToBlocks. Let me look at that logic again:
 
-        Read src/components/EventDisplay.tsx
+        Read ../src/components/EventDisplay.tsx
 
       Ah! I see the problem now. In the test, we're providing a single event with one message containing 3
        text blocks. EventDisplay keeps the text blocks separate in uniqueContent (lines 36-54), so they
@@ -269,7 +269,7 @@ describe("EventDisplay replay tests", () => {
 
       Let me print what lastFrame() actually returns by modifying the test temporarily:
 
-        Edit src/components/EventDisplay.test.tsx
+        Edit ../src/components/EventDisplay.test.tsx
 
         $ pnpm test EventDisplay.test.tsx 2>&1 | grep -A 20 "merges consecutive"
 
@@ -280,7 +280,7 @@ describe("EventDisplay replay tests", () => {
       This means the EventDisplay deduplication logic is keeping them separate, OR there's a bug in my
       eventToBlocks implementation. Let me add logging to eventToBlocks to see:
 
-        Edit src/components/eventToBlocks.ts
+        Edit ../src/components/eventToBlocks.ts
 
         $ pnpm test EventDisplay.test.tsx 2>&1 | grep -A 30 "eventToBlocks content"
 
@@ -296,9 +296,9 @@ describe("EventDisplay replay tests", () => {
       But the output still shows them on 3 separate lines. This means my merging logic isn't working. Let
       me add more logging to see what's happening in the loop:
 
-        Edit src/components/eventToBlocks.ts
+        Edit ../src/components/eventToBlocks.ts
 
-        Edit src/components/eventToBlocks.ts
+        Edit ../src/components/eventToBlocks.ts
 
         $ pnpm test EventDisplay.test.tsx 2>&1 | grep -A 50 "merges consecutive text blocks to prevent
       unwanted gaps"
@@ -341,7 +341,7 @@ describe("EventDisplay replay tests", () => {
       Let me check if the problem is in how StreamingText uses fragments. When you return a fragment with
       multiple <Text> components in Ink, they might be rendered on separate lines. Let me check:
 
-        Read src/components/StreamingText.tsx
+        Read ../src/components/StreamingText.tsx
 
       The issue is that StreamingText returns a fragment with multiple <Text> components. In Ink, these
       might be rendered as separate blocks. The fix is to wrap them in a single <Text> component or use
@@ -350,17 +350,17 @@ describe("EventDisplay replay tests", () => {
       Let me look at how Ink handles multiple Text components. Actually, the fix is simple - wrap all the
       text parts in a single Box or Text component with inline rendering:
 
-        Edit src/components/StreamingText.tsx
+        Edit ../src/components/StreamingText.tsx
 
-        Edit src/components/StreamingText.tsx
+        Edit ../src/components/StreamingText.tsx
 
       Now let me remove the console.log statements and test:
 
-        Edit src/components/eventToBlocks.ts
+        Edit ../src/components/eventToBlocks.ts
 
-        Edit src/components/eventToBlocks.ts
+        Edit ../src/components/eventToBlocks.ts
 
-        Edit src/components/EventDisplay.test.tsx
+        Edit ../src/components/EventDisplay.test.tsx
 
       Now let me run all tests:
 
@@ -372,13 +372,13 @@ describe("EventDisplay replay tests", () => {
 
       Excellent! Now let me update the todo list and progress file, then commit:
 
-        Read .ralph/todo.md
+        Read ../.ralph/todo.md
 
-        Edit .ralph/todo.md
+        Edit ../.ralph/todo.md
 
-        Read .ralph/progress.md
+        Read ../.ralph/progress.md
 
-        Edit .ralph/progress.md
+        Edit ../.ralph/progress.md
 
       Now let me format the code with Prettier:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herbcaudill/ralph",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Autonomous AI iteration engine for Claude CLI",
   "type": "module",
   "main": "./dist/index.js",
@@ -59,7 +59,7 @@
     "typecheck": "tsc --noEmit",
     "ralph": "tsx src/index.ts",
     "test:all": "pnpm typecheck && pnpm test",
-    "test": "vitest --exclude test/e2e/** run",
+    "test": "vitest run",
     "test:e2e": "vitest --config vitest.e2e.config.ts",
     "test:watch": "vitest --watch",
     "test:ui": "vitest --ui",

package/templates/prompt-beads.md

@@ -19,7 +19,7 @@ If there are none:
 
 ### Step 3: Select a task
 
-Select the highest-priority issue to work on. Use your best judgement.
+Select the highest-priority issue to work on. Finish in-progress tasks first. Bugs take priority. Otherwise use your best judgement.
 
 ### Step 4: Work on a single task
 

package/README.md

@@ -1,183 +0,0 @@
-```
-█▀█ ▄▀█ █   █▀█ █ █
-█▀▄ █▀█ █▄▄ █▀▀ █▀█
-```
-
-Autonomous AI iteration engine for Claude CLI. Ralph runs Claude in a loop to systematically work through your codebase's task list, enabling Claude to tackle work items iteratively.
-
-https://github.com/user-attachments/assets/e8d89a33-8db5-4d72-9c97-927558f92516
-
-## Overview
-
-Ralph spawns individual Claude CLI sessions that:
-
-1. Check project health (build, tests)
-2. Select and work on the highest-priority task
-3. Validate changes with tests
-4. Commit changes
-5. Repeat
-
-## Installation
-
-```bash
-pnpm add -D @herbcaudill/ralph
-```
-
-Or use directly with npx:
-
-```bash
-npx @herbcaudill/ralph
-```
-
-## Quick start
-
-1. **Initialize ralph in your project:**
-
-   ```bash
-   npx @herbcaudill/ralph init
-   ```
-
-   This creates a `.ralph/` directory with template files:
-   - `prompt.md` - Instructions for Claude during each iteration
-   - `todo.md` - Your task list (optional if using bd)
-   - `events.jsonl` - Event log in JSONL format (auto-generated during runs)
-
-2. **Customize the workflow:**
-
-   Edit `.ralph/prompt.md` to match your project's workflow (build commands, test commands, etc.).
-
-3. **Add tasks:**
-
-   You can manage tasks using either a markdown file or [beads](https://github.com/steveyegge/beads), a lightweight issue tracker.
-
-   **Option A: Using `.ralph/todo.md`**
-
-   ```markdown
-   ### To do
-
-   - [ ] Add user authentication
-   - [ ] Fix login form validation
-   - [ ] Write tests for auth flow
-
-   ---
-
-   ### Done
-   ```
-
-   **Option B: Using beads (recommended)**
-
-   ```bash
-   # Install bd
-   brew install herbcaudill/tap/bd
-
-   # Initialize in your project
-   bd init
-
-   # Create issues
-   bd create "Add user authentication"
-   bd create "Fix login form validation"
-   bd create "Write tests for auth flow"
-
-   # View ready work
-   bd ready
-   ```
-
-4. **Run ralph:**
-
-   ```bash
-   npx ralph          # Run with dynamic default (120% of open issues)
-   npx ralph 5        # Run 5 iterations
-   npx ralph --watch  # Run and watch for new issues
-   ```
-
-## Commands
-
-| Command         | Description                                                    |
-| --------------- | -------------------------------------------------------------- |
-| `ralph`         | Run with dynamic default (120% of open issues, min 10 max 100) |
-| `ralph <n>`     | Run specified number of iterations                             |
-| `ralph init`    | Initialize .ralph directory with templates                     |
-| `ralph --watch` | Watch for new issues after completion                          |
-| `ralph --help`  | Show help                                                      |
-
-## Watch mode
-
-Watch mode (`--watch`) keeps ralph running after completing all tasks, waiting for new issues to be added:
-
-```bash
-npx ralph --watch
-```
-
-When ralph finishes all available work and Claude outputs the completion signal, instead of exiting, it enters a waiting state. When you add a new issue via `bd create` or `bd q`, ralph automatically detects it and starts a new iteration to work on it.
-
-This enables a "continuous integration" style workflow:
-
-1. Start ralph in watch mode: `npx ralph --watch`
-2. Add tasks as you think of them: `bd q "Fix header alignment"`
-3. Ralph automatically picks up and works on new tasks
-4. Keep adding tasks while ralph works
-
-Watch mode requires **bd** (beads) for issue tracking—it watches for mutations to the beads database.
-
-## Configuration
-
-**`.ralph/prompt.md`**
-
-Instructions for Claude's workflow. Customize this for your project:
-
-- Build/typecheck commands
-- Test commands
-- Project-specific conventions
-- Commit message style
-
-### Customizing the prompt
-
-The default prompt ([for beads](./templates/prompt-beads.md) or [for TODO.md](./templates/prompt-todos.md)) works for my projects, but you should customize it for your project. Replace with your actual build/test commands (e.g., `pnpm build`, `cargo test`, `pytest`, etc.).
-
-## How it works
-
-Ralph is a thin wrapper around the Claude CLI that:
-
-1. **Spawns Claude CLI** with your project context (prompt, todo, progress files)
-2. **Captures output** as streaming JSON events
-3. **Processes events** to display tool usage (Read, Edit, Bash, etc.) in a readable format
-4. **Logs everything** to `events.jsonl` for debugging
-5. **Detects completion** when Claude outputs `<promise>COMPLETE</promise>`
-6. **Recursively runs** next iteration until count reached or todo list complete
-
-## Requirements
-
-- **Claude CLI** must be installed and configured
-- **Node.js** 18 or higher
-- Git repository (for commits)
-
-Install Claude CLI:
-
-```bash
-# macOS/Linux
-curl https://claude.com/cli | sh
-
-# Or with Homebrew
-brew install anthropics/tap/claude
-```
-
-Configure Claude CLI:
-
-```bash
-claude auth
-```
-
-## Tips
-
-- **Start with small iteration counts** (3-5) to verify the workflow before running longer sessions
-- **Customize prompt.md** for your project's specific needs (build commands, test frameworks, etc.)
-- **Break down complex tasks** into smaller subtasks in todo.md
-- **Let Claude prioritize** by not ordering tasks strictly - Claude will choose what makes sense
-
-## License
-
-MIT
-
-## Author
-
-Herb Caudill