@th0rgal/ralph-wiggum 1.0.5 → 1.0.7

package/README.md

@@ -17,7 +17,6 @@
   <a href="#what-is-ralph">What is Ralph?</a> •
   <a href="#installation">Installation</a> •
   <a href="#quick-start">Quick Start</a> •
-  <a href="#which-approach">Which Approach?</a> •
   <a href="#commands">Commands</a>
 </p>
 
@@ -27,6 +26,8 @@
 
 Ralph is a development methodology where an AI agent receives the **same prompt repeatedly** until it completes a task. Each iteration, the AI sees its previous work in files and git history, enabling self-correction and incremental progress.
 
+This package provides a **CLI-only** implementation (no OpenCode plugin).
+
 ```bash
 # The essence of Ralph:
 while true; do
@@ -44,12 +45,26 @@ done
 | **Persistence** | Walk away, come back to completed work |
 | **Iteration** | Complex tasks broken into incremental progress |
 | **Automation** | No babysitting—loop handles retries |
+| **Observability** | Monitor progress with `--status`, see history and struggle indicators |
+| **Mid-Loop Guidance** | Inject hints with `--add-context` without stopping the loop |
 
 ## Installation
 
 **Prerequisites:** [Bun](https://bun.sh) and [OpenCode](https://opencode.ai)
 
-### macOS / Linux
+### npm (recommended)
+
+```bash
+npm install -g @th0rgal/ralph-wiggum
+```
+
+### Bun
+
+```bash
+bun add -g @th0rgal/ralph-wiggum
+```
+
+### From source
 
 ```bash
 git clone https://github.com/Th0rgal/ralph-wiggum
@@ -57,8 +72,6 @@ cd opencode-ralph-wiggum
 ./install.sh
 ```
 
-### Windows (PowerShell)
-
 ```powershell
 git clone https://github.com/Th0rgal/ralph-wiggum
 cd opencode-ralph-wiggum
@@ -67,8 +80,6 @@ cd opencode-ralph-wiggum
 
 This installs:
 - `ralph` CLI command (global)
-- OpenCode commands (`/ralph-loop`, `/cancel-ralph`, `/help`)
-- OpenCode plugin with custom tools
 
 ## Quick Start
 
@@ -83,57 +94,9 @@ ralph "Build a REST API for todos with CRUD operations and tests. \
   --max-iterations 20
 ```
 
-## Which Approach?
-
-This implementation provides **two ways** to run Ralph loops:
-
-### CLI Loop (Recommended)
-
-External loop that calls `opencode run` repeatedly.
-
-```bash
-ralph "Your task" --max-iterations 10
-```
-
-| Pros | Cons |
-|------|------|
-| ✅ Works with any OpenCode version | ❌ Each iteration is a fresh session |
-| ✅ Simple and predictable | ❌ No conversation context between iterations |
-| ✅ Easy to debug | |
-| ✅ Auto-commit between iterations | |
-
-**Best for:** Most use cases, especially tasks with clear success criteria.
-
-### Plugin Loop (Experimental)
-
-In-session continuation using OpenCode's SDK events.
-
-```bash
-# In OpenCode TUI, use the ralph_start tool:
-# "Start a Ralph loop to build X"
-```
-
-| Pros | Cons |
-|------|------|
-| ✅ Single session context | ❌ Depends on OpenCode plugin API |
-| ✅ More efficient | ❌ Experimental—API may change |
-| ✅ Tools available in-session | ❌ Harder to debug |
-
-**Best for:** Long-running tasks where conversation context matters.
-
-### Decision Guide
-
-| If you need... | Use |
-|---------------|-----|
-| Reliability | CLI Loop |
-| Auto-commits | CLI Loop |
-| Conversation context | Plugin Loop |
-| Scripting/automation | CLI Loop |
-| First time trying Ralph | CLI Loop |
-
 ## Commands
 
-### CLI
+### Running a Loop
 
 ```bash
 ralph "<prompt>" [options]
@@ -150,44 +113,78 @@ Options:
   --help                   Show help
 ```
 
-### OpenCode Commands
+### Monitoring & Control
 
 ```bash
-/ralph-loop <prompt>       # Start a loop with the given task
-/cancel-ralph              # Cancel the active loop
-/help                      # Show Ralph Wiggum documentation
-```
+# Check status of active loop (run from another terminal)
+ralph --status
 
-### Plugin Tools
+# Add context/hints for the next iteration
+ralph --add-context "Focus on fixing the auth module first"
 
-When the plugin is active, these tools are available in OpenCode:
+# Clear pending context
+ralph --clear-context
+```
 
-| Tool | Description |
-|------|-------------|
-| `ralph_start` | Start a loop with prompt, max iterations, completion promise |
-| `ralph_status` | Check current loop status and iteration |
-| `ralph_cancel` | Cancel the active loop |
+### Status Dashboard
 
-## Troubleshooting
+The `--status` command shows:
+- **Active loop info**: Current iteration, elapsed time, prompt
+- **Pending context**: Any hints queued for next iteration
+- **Iteration history**: Last 5 iterations with tools used, duration
+- **Struggle indicators**: Warnings if agent is stuck (no progress, repeated errors)
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║                    Ralph Wiggum Status                           ║
+╚══════════════════════════════════════════════════════════════════╝
+
+🔄 ACTIVE LOOP
+   Iteration:    3 / 10
+   Elapsed:      5m 23s
+   Promise:      COMPLETE
+   Prompt:       Build a REST API...
+
+📊 HISTORY (3 iterations)
+   Total time:   5m 23s
+
+   Recent iterations:
+   🔄 #1: 2m 10s | Bash:5 Write:3 Read:2
+   🔄 #2: 1m 45s | Edit:4 Bash:3 Read:2
+   🔄 #3: 1m 28s | Bash:2 Edit:1
+
+⚠️  STRUGGLE INDICATORS:
+   - No file changes in 3 iterations
+   💡 Consider using: ralph --add-context "your hint here"
+```
 
-### "ralph-wiggum is not yet ready for use. This is a placeholder package."
+### Mid-Loop Context Injection
 
-OpenCode is trying to load the npm package `ralph-wiggum`, which is a placeholder.
-Remove `ralph-wiggum` from your OpenCode `plugin` list (opencode.json), or run:
+Guide a struggling agent without stopping the loop:
 
 ```bash
-ralph "Your task" --no-plugins
+# In another terminal while loop is running
+ralph --add-context "The bug is in utils/parser.ts line 42"
+ralph --add-context "Try using the singleton pattern for config"
 ```
 
-### "Cannot find module '@opencode-ai/plugin'"
+Context is automatically consumed after one iteration.
+
+## Troubleshooting
+
+### "ralph-wiggum" plugin errors
 
-OpenCode is loading the `@th0rgal/ralph-wiggum` npm package, but its dependencies aren't installed.
-Reinstall/upgrade the package so dependencies are present, or temporarily disable non-auth plugins:
+This package is **CLI-only**. If OpenCode tries to load a `ralph-wiggum` plugin,
+remove it from your OpenCode `plugin` list (opencode.json), or run:
 
 ```bash
 ralph "Your task" --no-plugins
 ```
 
+### "bun: command not found"
+
+Install Bun: https://bun.sh
+
 ## Writing Good Prompts
 
 ### Include Clear Success Criteria
@@ -280,34 +277,38 @@ ralph "Your task" --max-iterations 20
 
 ```
 ralph-wiggum/
-├── ralph.ts                      # CLI loop script
+├── bin/ralph.js                  # CLI entrypoint (npm wrapper)
+├── ralph.ts                      # Main loop implementation
 ├── package.json                  # Package config
-├── install.sh                    # Installation script
-├── uninstall.sh                  # Uninstallation script
-└── .opencode/
-    ├── command/
-    │   ├── ralph-loop.md         # /ralph-loop command
-    │   ├── cancel-ralph.md       # /cancel-ralph command
-    │   └── help.md               # /help command
-    └── plugin/
-        └── ralph-wiggum.ts       # OpenCode plugin
+├── install.sh / install.ps1     # Installation scripts
+└── uninstall.sh / uninstall.ps1 # Uninstallation scripts
 ```
 
+### State Files (in .opencode/)
+
+During operation, Ralph stores state in `.opencode/`:
+- `ralph-loop.state.json` - Active loop state
+- `ralph-history.json` - Iteration history and metrics
+- `ralph-context.md` - Pending context for next iteration
+
 ## Uninstall
 
 ```bash
-./uninstall.sh
+npm uninstall -g @th0rgal/ralph-wiggum
 ```
 
 ```powershell
-.\uninstall.ps1
+npm uninstall -g @th0rgal/ralph-wiggum
 ```
 
 ## Learn More
 
 - [Original technique by Geoffrey Huntley](https://ghuntley.com/ralph/)
 - [Ralph Orchestrator](https://github.com/mikeyobrien/ralph-orchestrator)
-- [Claude Code Plugin](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum)
+
+## See Also
+
+Check out [OpenAgent](https://github.com/Th0rgal/openagent) - a dashboard for orchestrating AI agents with workspace management, real-time monitoring, and multi-agent workflows.
 
 ## License