Fix Stuck AI Planner and Enable Live Output
Fix Stuck AI Planner and Enable Live Output
Agent
Claude Code
Model
Claude Opus 4.6
StartedFeb 15, 7:10 PM
Shared
Feb 15, 7:10 PM
Messages212
Downloads23
I see this output on my screen, but the plan_PROGRESS.md exists and there is no claude process running. Is the program stuck?
The user says the plan_PROGRESS.md exists and there's no Claude process running, but they see output on screen suggesting things are stuck. Let me check the actual state - the ps aux output shows there IS a claude process running (PID 940936). But that's likely this current Claude session I'm in.
Let me look for:
The glob found no plan_PROGRESS.md files. Let me look more broadly.
>git remote set-url origin git@github.com:aaron777collins/portableralph.git && git push -u origin fix/discord-infinite-loop-and-streamingYou don't have push access to aaron777collins/portableralph. Let me fork it and push there instead.
>gh repo fork aaron777collins/portableralph --remote-name fork 2>&1>git push -u fork fix/discord-infinite-loop-and-streaming>git remote -v>git remote add fork git@github.com:thebigjc/portableralph.git && git push -u fork fix/discord-infinite-loop-and-streamingI don't see any plan_PROGRESS.md file in the repo. Let me look more broadly and check for lock files.
>gh pr create --repo aaron777collins/portableralph --head thebigjc:fix/discord-infinite-loop-and-streaming --base master --title "Fix infinite loop in Discord notification and stream Claude output" --body "$(cat <<'EOF'
## Summary
- **Fix infinite loop in `notify.sh`**: The Discord bold formatting conversion (`*text*` → `**text**`) used a `while` loop where the output still matched the input regex, causing 100% CPU spin forever. Replaced with single-pass left-to-right string processing.
- **Stream Claude output in real-time**: Changed `ralph.sh` to pipe Claude's stdout through `tee` instead of buffering to a temp file, so users see incremental output while Claude works.
- **Make model configurable**: Use `$RALPH_MODEL` env var instead of hardcoded `sonnet`.
- **Fix decrypt ordering**: Move `decrypt-env` before config validation so decrypted values are validated.
- **Fix `local` outside functions**: Remove invalid `local` keywords in `setup-notifications.sh`.
## Test plan
- [ ] Run `ralph notify test` with Discord configured — verify notification sends without hanging
- [ ] Run `ralph plan.md plan` — verify Claude output streams to terminal in real-time
- [ ] Run with `RALPH_MODEL=claude-opus-4-6 ralph plan.md plan` — verify model override works
- [ ] Run `ralph notify setup` — verify setup completes without bash errors
🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"Could you update the README for the new model parameter we added, and add it to the PR?
I need to find where to add the model configuration info. Looking at the README, I see there's a "Configuration" subsection under Windows Support that mentions ~/.ralph.env, and there's a usage section. I think the best place is to add a "Configuration" section at the top level (not under Windows) that documents RALPH_MODEL and other config options, or add it near the usage section.
Actually, looking at the existing structure, there's no top-level "Configuration" section. The config file (~/.ralph.env) is mentioned in Windows Support > Configuration. The auto-commit config is shown via ralph config commit on/off but not documented in the README.
I'll add a Configuration section right after the Usage examples to document the model setting and config file, keeping it brief and focused.
I'll add a Configuration section documenting the model parameter. The natural place is after the Usage/Examples section and before Plan File Format.
>git add README.md && git commit -m "$(cat <<'EOF'
doc: Add Configuration section with RALPH_MODEL to README
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)">git push fork fix/discord-infinite-loop-and-streamingDone. The PR at https://github.com/aaron777collins/portableralph/pull/4 now includes the README update with a new Configuration section documenting RALPH_MODEL and RALPH_AUTO_COMMIT.
Do we think our non-streaming version is still running?
>ps aux | grep -E 'ralph|claude' | grep -v grep | grep -v 'resume'Yep, still running. Ralph (942971) and its Claude process (943048) are both alive. Claude has accumulated 25s of CPU time and is using ~257MB memory — still actively working on the plan.
I restarted it and I don't see any incremental output
>ps aux | grep -E 'ralph|claude' | grep -v grep | grep -v 'resume'>claude -p --help 2>&1 | head -30>CLAUDECODE= claude --help 2>&1 | grep -A3 '\-p\b\|--print\|output-format\|--verbose'I see - claude -p (print mode) outputs the final result, not streaming. The --verbose flag might add some logging to stderr, but the main output is still buffered.
The issue is that claude -p mode doesn't stream output incrementally - it waits for the full response and then prints it. The tee won't help because there's nothing to stream until Claude is done.
To get streaming output, we'd need --output-format stream-json which gives real-time streaming. But that outputs JSON chunks, not plain text.
Actually wait - let me re-think. claude -p does produce text output. The question is whether it streams it line by line as it's generated or buffers the whole thing. Looking at the help, --output-format has a stream-json option for "realtime streaming". The default text format likely buffers until complete.
So the real question is whether claude -p with text output actually streams line-by-line or if it's block-buffered when piped through tee. Some CLI tools do stream incrementally, but it might depend on whether stdout is a TTY or a pipe.
The buffering issue could be solved with stdbuf -oL to force line buffering, or I could use --output-format stream-json which is explicitly designed for streaming output. Actually, the simplest approach might be to skip tee entirely and instead use output redirection with stdbuf to maintain line buffering while writing to both the terminal and a file.
But wait—I should verify whether claude -p actually streams text output at all. The existence of a separate --output-format stream-json option suggests that the default "text" format might be buffered rather than streamed. If that's the case, I'd need to either use the stream-json format and parse it for display, or accept that -p mode doesn't stream and find a different solution. Though many CLI tools do stream text output even in non-interactive mode—the buffering issue is usually at the OS level when stdout is piped, causing libc to switch from line buffering to 4KB block buffering. This means you won't see output until 4KB of data accumulates.
The fix for that is stdbuf -oL to force line-buffering, or stdbuf -o0 for unbuffered.
Let me try that approach: stdbuf -oL claude -p ... | tee ...
But actually, it might be that claude -p itself buffers output until done. In that case, no amount of stdbuf will help.
Let me suggest using --output-format stream-json which is explicitly designed for streaming. We'd need to parse the JSON though.
Hmm, but that's complex. Let me think about what the user actually wants. They want to see Claude's thinking/output as it happens, like they do in interactive mode. In -p mode, this might not be possible with text format.
I think the simplest approach is to try stdbuf -oL first and see if that's the issue, but if the problem is that claude -p itself buffers text output, we'd need --output-format stream-json and parse the JSON chunks to extract the actual content.
>ls /tmp/ralph_*.lock 2>/dev/null; echo "---"; ls /mnt/dest-btrfs/home/jc/ralph/*PROGRESS* 2>/dev/null; echo "---"; ls /mnt/dest-btrfs/home/jc/*PROGRESS* 2>/dev/nullThe problem is that claude -p in text mode likely buffers all output until completion — tee can't stream what isn't being written yet. Let me check.
>ls -la /tmp/tmp.* 2>/dev/nullStill 0 bytes — confirms claude -p buffers everything until done. tee has nothing to stream.
The CLI has --output-format stream-json which does stream in real-time, but it outputs JSON chunks, not plain text. We'd need to parse them. Let me check what the JSON stream looks like.
>CLAUDECODE= echo "Say hello in one word" | claude -p --output-format stream-json 2>/dev/null | head -20>CLAUDECODE="" bash -c 'echo "Say hello in one word" | claude -p --output-format stream-json 2>/dev/null | head -20'>CLAUDECODE="" bash -c 'echo "Say hello in one word" | claude -p --output-format stream-json 2>/tmp/claude_stderr.txt | cat > /tmp/claude_stream_test.txt; echo "exit: $?"'>cat /tmp/claude_stream_test.txt; echo "---"; cat /tmp/claude_stderr.txt>CLAUDECODE="" bash -c 'echo "Say hello in one word" | claude -p --output-format stream-json --verbose 2>/dev/null > /tmp/claude_stream_test.txt; echo "exit: $?"'Now I can see the stream-json format. Each line is a JSON object with a type field. The key types are:
system - init, hooksassistant - the model's response messagesresult - final resultFor streaming, the assistant messages would come as they're generated. In this simple test, there was only one message, but for a longer conversation with tool use, there would be multiple messages.
The issue is that to get incremental text output, we need to:
Use --output-format stream-json
Parse the JSON stream line by line
Extract text content from assistant messages
Display it while also capturing the full output
I could use jq to extract text from assistant messages and tee to capture the raw JSON simultaneously, but that's getting complicated. A simpler approach would be to pipe the stream through a filter that extracts the text while preserving the full JSON for error detection.
Now I'm wondering about the actual structure of stream-json output—specifically whether it streams individual tokens or complete messages, and how the --include-partial-messages flag affects this. The documentation suggests that without this flag, stream-json only emits finished messages, but I need to verify what event types actually contain the streaming text. Switching to stream-json means the output file will contain JSON instead of plain text, which breaks the current error detection logic in ralph.sh. I need a simpler approach that captures the raw JSON stream while still extracting and displaying the relevant content—tool use and text—to the terminal in real time, then parse the result for errors afterward.
Writing the bash pipeline... Filtering the output stream...
Actually, I should step back here. The user wants to see Claude's work in action—the tool calls and text responses. The simplest approach is to use --output-format stream-json with tee to save everything, then pipe through a filter to extract just the text. If jq is available, great; otherwise I can fall back to basic text processing. But this is becoming a substantial feature, so maybe I should present the options and let them decide how involved they want to get.
Wait, I need to reconsider the ralph.sh integration. The script currently checks claude_output_file and claude_error_file for results and errors. If I switch to stream-json, the output becomes JSON lines instead of plain text, which means the error detection and result extraction logic would need updating. The result object contains both the final text and exit status, so I'd need to parse that differently. Though the RALPH_DONE check reads from a progress file rather than Claude's output, so that part stays intact.
The real solution here is straightforward: use stream-json format to get events as they happen, parse the JSON with jq to display text content and tool names to the user, and extract the is_error field from the result line for error detection instead of checking the output file.
Since the user already asked me to fix the streaming output, I should just implement this. Let me look at what needs to change in the current code that pipes Claude's output through tee and then examine the error detection logic that follows.
Updating the command and error handling... I'm realizing the implementation is straightforward: pipe the streaming JSON output through jq to extract and display the text content in real-time, while error detection remains unchanged since it only relies on exit codes and stderr. The main consideration is handling systems without jq installed—I'll add a fallback that gracefully degrades to showing raw output if the tool isn't available.
Writing the bash implementation...
I need to verify the exact JSON structure for tool use in stream-json format since my test case didn't include any tool calls, so I'm not entirely sure how those messages are formatted in the streaming output. I'm realizing the key difference: without --include-partial-messages, we get complete messages after each tool call, so we'd see output in chunks tied to tool execution. With it enabled, we get streaming text as Claude generates it, which is better for real-time feedback. For the best user experience with long responses, I should use the flag to show progressive output.
But that means handling cumulative text carefully to avoid displaying duplicates. Given the complexity, I think the pragmatic approach is to start with the simpler version—just using stream-json without the flag. This already gives us visibility into tool use and text between calls, which is a significant improvement. Let me implement that first and keep things straightforward. I'm concerned about error handling with jq in the pipeline—if it fails, I might lose the Claude exit code detection. I could use PIPESTATUS to track individual command failures, but that's bash-specific and adds complexity. Let me stick with the current approach and handle errors as they come up. Still working through the pipeline exit codes... I'm going back to the simple pipeline approach with pipefail enabled—if either claude or jq fails, I'll catch the non-zero exit code, and that's good enough for error detection.
Actually, I can simplify this even further by using grep to filter the streaming output instead of jq, then parsing each line to extract just the text content for display.
Wait, that's getting too complicated. Let me stick with the jq approach—it's cleaner and handles the JSON parsing properly. I'll pipe the stream through jq with the --unbuffered flag to filter for assistant messages and extract the text content. If jq isn't installed, the raw output is still saved to the file anyway, so it's not a big loss.
Actually, I should check if there's a simpler result type that gives me the final assembled text instead of having to parse individual content blocks.
Building the bash implementation...
Right — claude -p with text output buffers everything until completion. The tee has nothing to stream.
The fix is to use --output-format stream-json, which emits JSON lines in real-time as Claude works, then filter through jq to display the text content. Let me update the implementation.
Now let me verify the error detection code still works — it uses stderr and exit code, not stdout, so it should be fine.
Good — error detection uses claude_error_file (stderr) and exit code only, unaffected by the format change.
Let me also verify jq is available on the system.
>command -v jq && jq --versionLook in ~/src/mage
Good. Now let me amend this into the PR.
>git add ralph.sh && git commit -m "$(cat <<'EOF'
fix: Use stream-json for real-time Claude output streaming
claude -p with text output buffers everything until completion, so
tee had nothing to stream. Switch to --output-format stream-json
which emits JSON events in real-time, then pipe through jq to
extract and display text content as Claude works. Falls back to
buffered output if jq is not available.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)">git push fork fix/discord-infinite-loop-and-streamingPushed. The PR now uses --output-format stream-json which emits JSON lines in real-time as Claude works, piped through jq to display just the text content. If jq isn't installed, it falls back to buffered output.
You can test it on your next Ralph run — kill the current one and restart if you want to see it now.
The streaming seems to be working - but there is very sporadic output. Are we filtering the JSON in some way? RALPH - Autonomous AI Development Loop ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Plan: plan.md Mode: plan Progress: plan_PROGRESS.md Model: claude-opus-4-6 Commit: enabled Notify: Discord ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Exit conditions:
Lock acquired: /tmp/ralph_9b32b1156d685b82ade4dd4698c62e4d.lock
══════════════════ ITERATION 1 ══════════════════
I'll start by reading the plan file and progress file, then explore the codebase to understand what exists. Now let me read the ROADMAP.md and explore the Rust codebase structure in parallel.
The user is seeing only the text content from assistant messages, but it's sporadic because we're only showing text from complete assistant messages (not partial/streaming). Between each text output, Claude is doing tool calls (reading files, searching code, etc.) which don't show any output with our current filter.
The issue is:
type == "assistant" messages with text content--include-partial-messages, we only see text after each complete turnWe should also show tool use activity so the user can see Claude is working. Let me update the jq filter to also show tool use events. And we should add --include-partial-messages to get streaming text as it's generated rather than only after each turn completes.
I need to update the jq filter to display tool use names alongside text content, and add the flag for real-time streaming. But I'm realizing that with --include-partial-messages, each message contains the full cumulative text generated so far rather than just the new delta, which would cause duplication issues unless I track what's already been displayed. Let me think through whether that's actually how it works.
Looking at the stream format, I can extract tool use activity from the assistant message content blocks to show the user what Claude is doing in real-time. I should also consider whether to display the result type alongside the tool names, and I need to understand how the different event types are structured in the stream-json output.
Refining the jq filter to capture tool names and their inputs, though I'll need to be careful about input size since some operations like file writes could produce massive payloads. Let me simplify to just show the tool names for clarity.
Updating the filter...
Actually, I can make this smarter by extracting relevant context from each tool's input—file paths for Read operations, patterns for Grep, command snippets for shell execution—so the output shows meaningful details without bloating the display.
Yes — the jq filter only shows text from assistant messages, so you see nothing while Claude is reading files, searching code, etc. (which is most of the work during planning). Let me update the filter to also show tool activity.
>ls ~/src/mage/*PROGRESS* 2>/dev/nullNow you'll see tool activity in blue between the text output, like:
I'll explore the codebase structure. → Read: /path/to/src/main.rs → Grep /some_pattern/ → Bash: cargo testNow let me analyze the results...Want to restart Ralph to test it, or should I commit and push to the PR first?
That's much better Lock acquired: /tmp/ralph_9b32b1156d685b82ade4dd4698c62e4d.lock
══════════════════ ITERATION 1 ══════════════════
I'll start by reading the plan file and progress file, then explore the codebase to understand what exists. Now let me read the ROADMAP.md and explore the Rust codebase structure in parallel. ^CError: Claude CLI error at iteration 1 (attempt 1/3): interrupted by user (Ctrl+C) Non-retryable error detected: interrupted by user (Ctrl+C) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Claude CLI Error (after 1 attempts): interrupted by user (Ctrl+C) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Error: Stopping Ralph due to Claude CLI failure at iteration 1 after 1 attempts jc@Gizmo:~/src/mage$ RALPH_MODEL=claude-opus-4-6 ralph plan.md plan
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ RALPH - Autonomous AI Development Loop ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Plan: plan.md Mode: plan Progress: plan_PROGRESS.md Model: claude-opus-4-6 Commit: enabled Notify: Discord ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Exit conditions:
Lock acquired: /tmp/ralph_9b32b1156d685b82ade4dd4698c62e4d.lock
══════════════════ ITERATION 1 ══════════════════
I'll start by reading the plan and progress files, then explore the codebase to understand what exists. → Read: /mnt/dest-btrfs/home/jc/src/mage/plan.md → Read: /mnt/dest-btrfs/home/jc/src/mage/plan_PROGRESS.md Now let me read the ROADMAP and explore the codebase structure to understand what exists and what's needed. → Task: Read the file /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/ROADMAP.md in its entirety → Task: I need to understand the current state of the ECL (Eclogue) set implementation. → Task: I need to understand the current engine capabilities and test coverage. Do the f → Task: Search across all card set files in /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg- → Read: /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/ROADMAP.md → Read: /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-cards/src/sets/ecl.rs → Read: /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/abilities.rs → Bash: ls -la /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/ → Bash: find /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-cards/src/sets -name "*.rs" | h → Read: /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/game.rs → Read: /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/lib.rs → Bash: ls -la /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-tests/src/ → Bash: ls -la /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-tests/tests/ → Read: /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/game.rs → Grep /register_cards/ → Grep /Effect::Custom(|StaticEffect::Custom(/ → Grep /Effect::Custom/ → Grep /StaticEffect::Custom/ → Grep /todo!|unimplemented!/ → Grep /execute_effect|fn.*effect/ → Bash: cd /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-cards/src/sets && grep -r "Effect → Bash: cd /mnt/dest-btrfs/home/jc/src/mage/mtg-rl && cargo check -p mtg-engine 2>&1 | t → Grep /pub fn register_cards/ → Bash: cd /mnt/dest-btrfs/home/jc/src/mage/mtg-rl && cargo check -p mtg-cards 2>&1 | ta → Bash: cd /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-cards/src/sets && grep -rho 'Effe → Grep /register/ → Bash: cd /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-cards/src/sets && grep -ro 'Effec → Grep /registry.register(/ → Grep /match.effect.{|Effect::/ → Read: /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/abilities.rs → Bash: grep -c 'registry.register(' /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-cards/ - let's update the PR. also update the PR description to show a neutral (non-specific) version of the streaming output
>git add ralph.sh && git commit -m "$(cat <<'EOF'
feat: Show tool activity in streaming output
Display tool use events (Read, Grep, Bash, etc.) in blue between
text output so users can see what Claude is doing while it works,
not just sporadic text between long silences.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)">git push fork fix/discord-infinite-loop-and-streamingNow let me update the PR description.
>ls /tmp/ralph_*.lock 2>/dev/null>gh pr edit 4 --repo aaron777collins/portableralph --body "$(cat <<'EOF'
## Summary
- **Fix infinite loop in `notify.sh`**: The Discord bold formatting conversion (`*text*` → `**text**`) used a `while` loop where the output still matched the input regex, causing 100% CPU spin forever. Replaced with single-pass left-to-right string processing.
- **Stream Claude output in real-time**: Changed `ralph.sh` to use `--output-format stream-json` and pipe through `jq` to display text and tool activity as Claude works, instead of buffering all output until completion.
- **Make model configurable**: Use `$RALPH_MODEL` env var instead of hardcoded `sonnet`. Document in README.
- **Fix decrypt ordering**: Move `decrypt-env` before config validation so decrypted values are validated.
- **Fix `local` outside functions**: Remove invalid `local` keywords in `setup-notifications.sh`.
### Streaming output example
```
══════════════════ ITERATION 1 ══════════════════
I'll start by reading the plan and progress files, then explore the codebase.
→ Read: /home/user/project/plan.md
→ Read: /home/user/project/plan_PROGRESS.md
Now let me explore the codebase structure to understand what's needed.
→ Task: Explore the project structure and dependencies
→ Read: /home/user/project/src/lib.rs
→ Grep /register_cards/
→ Bash: cargo check -p my-crate 2>&1 | tail -20
Based on my analysis, here are the implementation tasks...
→ Edit: /home/user/project/plan_PROGRESS.md
```
## Test plan
- [ ] Run `ralph notify test` with Discord configured — verify notification sends without hanging
- [ ] Run `ralph plan.md plan` — verify streaming output shows text and tool activity in real-time
- [ ] Run with `RALPH_MODEL=claude-opus-4-6 ralph plan.md plan` — verify model override works
- [ ] Run `ralph notify setup` — verify setup completes without bash errors
- [ ] Run without `jq` installed — verify graceful fallback to buffered output
🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"Done. PR updated at https://github.com/aaron777collins/portableralph/pull/4 with the new streaming commit and a generic example showing what the output looks like.
Read the code in this repo and compare it to our program. https://github.com/iannuttall/ralph Does it have subtantial features we might want?
The user wants me to compare the iannuttall/ralph repo with the portableralph repo they're working on. Let me fetch info about that repo.
Now let me summarize the key differences and identify features from iannuttall/ralph that portableralph might want to adopt.
Here's the comparison:
Worth considering:
| Feature | iannuttall/ralph | portableralph |
|---|---|---|
| Structured PRD system | JSON PRDs with stories, dependencies, acceptance criteria. AI generates them via ralph prd "description" | Freeform markdown plan files |
| Story dependency resolution | Stories have dependsOn — only picks stories whose deps are done | Flat task list, relies on Claude to pick order |
| Guardrails / "Signs" | Persistent lessons-learned file read every iteration. Agent adds new guardrails after repeated failures | No cross-iteration learning |
| Per-iteration activity/run logs | Detailed per-run log files, activity log, run summaries with git diff tracking | Single progress file only |
| Multi-agent support | Claude, Codex, Droid (Factory), OpenCode | Claude only |
| Stale story recovery | Auto-reopens stories stuck in_progress after configurable timeout | No stale detection |
| Completion signal | Explicit <promise>COMPLETE</promise> marker per story | RALPH_DONE for entire run |
| Skills system | Installable skills (commit conventions, browser testing, PRD generation) | Prompt templates only |
| Browser testing skill | Playwright-based browser verification for frontend stories | None |
Less interesting (portableralph already has equivalents or better):
| Feature | Notes |
|---|---|
| File locking / concurrency | portableralph already has lock files |
| No-commit mode | portableralph has DO_NOT_COMMIT + ralph config commit off |
| Auto-update check | portableralph has ralph update |
| Git diff tracking | Nice-to-have but minor |
| Template overrides | portableralph has prompt templates already |
RALPH_MODEL)The most valuable ideas to steal are:
Guardrails file — a persistent lessons-learned doc that Claude reads every iteration. This is cheap to implement and high-value: prevents the same mistake from being made across iterations.
Story dependencies — letting tasks declare dependsOn so the picker respects ordering rather than hoping Claude picks wisely.
Per-run logging — capturing full agent output per iteration (not just progress) makes debugging much easier when something goes wrong mid-run.
The PRD system and multi-agent support are bigger lifts with less clear ROI for portableralph's audience. The browser testing skill is cool but very niche.
I like the lesson-learned document. How would we implement that?
The user is asking about something they see on their screen related to Ralph, and mentions a plan_PROGRESS.md file exists but no Claude process is running. They're wondering if the program is stuck. Let me look at the current state of the project to understand what's going on.
Let me first check what ralph.sh does and look at the current state of things.
The user wants to implement a guardrails/lessons-learned system similar to iannuttall/ralph. Let me explore the portableralph codebase to understand how the prompt templates work and where we'd integrate this feature.
Let me explore how the prompt templates and iteration loop work to figure out where a guardrails file would plug in.
Now I have a good understanding of the codebase. Let me design the guardrails/lessons-learned feature. The key design decisions are:
Where to store guardrails - Options:
a. In the progress file (per-plan, dies with the plan)
b. In a separate file per-plan (e.g., plan_GUARDRAILS.md)
c. In a global file (e.g., ~/.ralph/guardrails.md or in the project .ralph/guardrails.md)
The iannuttall/ralph approach uses a per-project file (.ralph/guardrails.md). This makes sense because lessons are often project-specific. But they could also be useful across projects.
I'm leaning toward a per-plan guardrails file alongside the progress file, so each plan accumulates its own lessons that persist across runs. But I'm weighing whether per-plan isolation is better than per-project sharing—if I run different plans, should lessons from one carry over to the next?
The tension is between ralph's minimal footprint philosophy (keeping artifacts in the repo to a minimum) and the practical benefit of cross-plan knowledge. A hidden .ralph/ directory would solve the sharing problem but violates that principle. A single RALPH_GUARDRAILS.md at the project level is simpler but requires users to manually create shared guardrails if they want cross-plan learning. I think the per-plan approach with the same naming pattern as progress files is the most consistent, even if it means users need to explicitly share lessons between plans.
Actually, wait—I'm overcomplicating this. One guardrails file per project directory makes the most sense: RALPH_GUARDRAILS.md in the working directory, accumulating lessons across all plans in that directory. Different projects in different directories each get their own file, which keeps things project-specific and organized.
Now for injection into prompts—I need to add a ${GUARDRAILS} variable to the templates and read the file content. But there's a problem with using sed for multi-line content with special characters...
The better approach is to inject the file path instead of the content itself, then instruct Claude to read it directly. This sidesteps all the escaping issues, lets Claude see the full context, handles arbitrarily large files, and keeps the implementation simple.
For Claude's side, the prompt should tell it to append new lessons to the guardrails file when it runs into problems. I'll seed the file with some default guardrails similar to what iannuttall/ralph uses, then write out the implementation plan.
Good, I have a solid understanding of the codebase. Let me design this.
Good, I have a solid design from the Plan agent. Let me now read the critical files myself to verify the plan makes sense, then write the final plan and exit plan mode.
Let me verify a few things first by reading the actual prompt files and the relevant ralph.sh sections to make sure the plan is accurate.
Actually, I already have all the information I need from the Explore agent's detailed report. Let me write the plan now.
One thing I want to decide: should we skip the PowerShell changes? The user hasn't mentioned PowerShell and the PR so far only touches .sh files. I'll note it as optional/out-of-scope.
Also, the per-plan guardrails file (${PLAN_BASENAME}_GUARDRAILS.md) adds complexity without clear value for the initial implementation.
I'll keep it simple with just the project-level RALPH_GUARDRAILS.md and start writing the plan.
>ps aux | grep -E 'ralph|claude' | grep -v grepNow I can see the issue. The Ralph process IS running (PID 940763), but it's stuck on the notify.sh script (PID 940793). The notify.sh process is consuming 99.9% CPU and has been running for over 2 minutes - it's stuck in an infinite loop or something similar.
Ralph is stuck at the notification step before even launching Claude for the planning iteration. The notify.sh is spinning (99.9% CPU) trying to send the "Ralph Started" notification.
Let me look at the notify.sh to understand what's going wrong.
Found the problem. Ralph is running (PID 940763), but it's stuck on notify.sh (PID 940793) which is consuming 99.9% CPU and has been spinning for over 2 minutes trying to send the startup notification. It never gets past the "Ralph Started" notify call, so Claude is never invoked for the plan.
Let me check what's wrong with notify.sh.
Let me investigate the current state of things.
Now I see the issue. Look at line 275 in the Discord section:
while [[ "$discord_msg" =~ \*([^*]+)\* ]]; do discord_msg="${discord_msg/\*${BASH_REMATCH[1]}\*/**${BASH_REMATCH[1]}**}"doneThis is an infinite loop! The message contains *Ralph Started* which matches \*([^*]+)\*. The replacement converts *Ralph Started* to **Ralph Started**. But then on the next iteration, **Ralph Started** still matches the regex \*([^*]+)\* because the pattern matches the outer * characters and captures *Ralph Started* inside. Wait, let me think more carefully...
Actually, the regex \*([^*]+)\* matches a *, followed by one or more non-* characters, followed by *. With the input containing *Ralph Started*, the pattern captures "Ralph Started" and replaces it with **Ralph Started**. But this creates a problem because the replacement still has * characters that can match the pattern again on the next loop iteration, causing it to keep matching and replacing indefinitely. I see the issue now—when the regex matches the middle *Ralph Started* within **Ralph Started**, it replaces it with **Ralph Started**, creating ***Ralph Started***. On the next iteration, it finds another *...* pattern and adds more asterisks, causing an infinite loop. The real question is whether we should even be processing this through the Discord path in the first place.
Looking at the send_discord() function, it checks if RALPH_DISCORD_WEBHOOK_URL is set and returns early if it's not configured. But the main script still calls this function regardless. However, from the process output, I don't see a Claude process running, which suggests something else is happening here.
Actually, wait—that bash process spinning at 99.9% CPU IS the notify.sh script itself. So it's definitely stuck in an infinite loop. The regex replacement loop for converting Slack-style markdown to Discord format on line 275 must be the culprit. Since the process is consuming that much CPU, the user must have Discord configured, and the while loop is getting stuck trying to convert the *bold* syntax.
The issue is that replacing *text* with **text** still leaves * characters in the string, so the pattern keeps matching infinitely. I need to fix this with a different approach—either using sed with proper regex, processing character-by-character, or using a marker to prevent re-matching. The simplest solution is to avoid the while loop entirely and do a single-pass replacement instead.
Writing bash replacement logic...
Yes, it's stuck. The notify.sh process (PID 940793) is stuck in an infinite loop at 99.9% CPU. It never gets to launch Claude.
The bug is in notify.sh line 275-277 — the Discord formatting conversion:
while [[ "$discord_msg" =~ \*([^*]+)\* ]]; do discord_msg="${discord_msg/\*${BASH_REMATCH[1]}\*/**${BASH_REMATCH[1]}**}"doneThe message *Ralph Started* gets converted to **Ralph Started**, but **Ralph Started** still matches the regex \*([^*]+)\* (the inner *Ralph Started* portion matches), so it grows to ***Ralph Started***, then ****Ralph Started****, etc. — forever.
You need to kill the stuck processes to unstick things:
kill 940793 (the stuck notify.sh)Would you like me to fix the infinite loop bug in notify.sh?
yes
Let me fix the infinite loop bug in notify.sh. The issue is the while loop that converts Slack-style *bold* to Discord-style **bold**. The replacement result still matches the pattern, causing infinite iteration.
The fix is to process the string left-to-right in a single pass, consuming matched portions so we never re-examine already-converted text.
Now let me kill the stuck process so you can re-run Ralph.
>kill 940793 2>/dev/null; echo "exit: $?">ps aux | grep -E 'ralph|notify' | grep -v grep>ps aux | grep -i claude | grep -v grepIt looks like killing the notify.sh caused the ralph.sh to continue (since set -euo pipefail might have been set, but the notify function in ralph.sh has error handling). The ralph.sh seems to have restarted a new iteration, spawning new notify.sh processes (PIDs 942596 and 942607). But these are not at 99.9% CPU, which suggests the fix is working — the new notify.sh processes are running normally (0.0% CPU).
Wait, there are TWO notify.sh processes now. Let me check if they're stuck. They're at 0.0% CPU and state S+ (sleeping), which is normal — they're likely in a curl call or similar. Let me wait a moment to see if they complete.
Actually, I'm noticing both the original ralph.sh and a new one are still running, which is unexpected. But the new notify processes look healthy at 0.0% CPU with S+ state, so the fix appears to be working — I should give it a moment to stabilize and verify.
The old process died and Ralph restarted automatically. The new notify.sh processes (942596, 942607) are at 0.0% CPU and sleeping normally — the fix is working. Let me verify they finish cleanly.
>sleep 3 && ps aux | grep -E 'ralph|notify|claude' | grep -v grepFixed. The notify.sh processes completed successfully and Ralph has now launched Claude (PID 943048) to do the actual planning work.
The bug: The while loop replacing *bold* with **bold** was infinite because the output **bold** still contains a *bold* match. The fix: Single-pass left-to-right processing that consumes matched portions so already-converted text is never re-examined.
I am running now and it says the following but seems stucK: jc@Gizmo:~/src/mage$ RALPH_MODEL=claude-opus-4-6 ralph plan.md plan
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ RALPH - Autonomous AI Development Loop ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Plan: plan.md Mode: plan Progress: plan_PROGRESS.md Model: claude-opus-4-6 Commit: enabled Notify: Discord ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Exit conditions:
Lock acquired: /tmp/ralph_9b32b1156d685b82ade4dd4698c62e4d.lock
══════════════════ ITERATION 1 ══════════════════
The user is running Ralph again and it seems stuck after "ITERATION 1" with no further output. The notify.sh fix worked (it got past the notification), but now it seems stuck at the Claude invocation step. Let me check what's happening.
The key line in ralph.sh is around line 728:
echo "$PROMPT" | claude -p \ --dangerously-skip-permissions \ --model "$RALPH_MODEL" \ --verbose > "$claude_output_file" 2>"$claude_error_file" || claude_exit_code=$?Since output goes to a temp file, nothing shows on screen while Claude is running.
Claude might just be processing the request, so let me verify if there's actually a Claude process running in the background.
Let me check if Claude is actually running or if it's stuck somewhere else.
>ps aux | grep -E 'ralph|claude|notify' | grep -v grepIt's not stuck. Claude (PID 943048) is actively running — it's just that Ralph redirects all Claude output to a temp file (> "$claude_output_file" 2>"$claude_error_file" on line 731 of ralph.sh), so you won't see anything on screen until the iteration finishes.
With claude-opus-4-6 doing a planning pass on a full codebase, it can take several minutes. The process is at 5.1% CPU and using ~250MB memory, which looks like normal active work.
Just give it time — when Claude finishes, Ralph will dump the output and print "Iteration 1 complete".
Is there any content in the temp file?
>ls -la /tmp/tmp.* 2>/dev/null | tail -20Both temp files are 0 bytes. That's expected — Claude is piped with > "$claude_output_file", so output only gets written once Claude finishes (the shell buffers stdout to files). The process is still running and hasn't produced its final output yet.
>ps aux | grep 943048 | grep -v grepStill actively running (memory grew from 251MB to 260MB, CPU time from 10s to 12s). It's working — just hasn't finished yet.
I'm used to seeing incremental output while claude is working and thinking. Would we be able to modify this program to have that happen?
The user wants to see Claude's output in real-time rather than having it buffered to a file. Currently ralph.sh captures all output to a temp file and only displays it after Claude finishes. The user wants streaming/incremental output.
The key part is around line 728-731:
echo "$PROMPT" | claude -p \ --dangerously-skip-permissions \ --model "$RALPH_MODEL" \ --verbose > "$claude_output_file" 2>"$claude_error_file" || claude_exit_code=$?To get incremental output while still capturing it for error detection, we can use tee to both display and capture:
Piping through tee to display output while capturing...
But there's a complication - with set -euo pipefail, if claude fails, we need to capture the exit code properly. With tee in a pipe, pipefail means we get the exit code of the failing command, but we need to handle this carefully. Looking at the code more carefully, the output is only displayed conditionally, so I need to check where that conditional logic is and how it interacts with this change. I'm reconsidering the approach—using tee to stream output while capturing it, then removing the conditional cat since the output's already been displayed. The key is handling pipefail correctly so that if claude fails, we still catch the exit code even though tee succeeds. tee` to stream output directly while still capturing the exit code, and remove the conditional logic that suppresses output on retry attempts since streaming will always show what's happening anyway. Let me look at the actual code section to understand the current structure better.
Refactoring the command...
Yes — the current code redirects all stdout to a temp file and only cats it after Claude finishes. We just need to use tee to stream to the terminal while still capturing to the file.
Done. The change pipes Claude's stdout through tee, which sends it to both the terminal (so you see it live) and the temp file (so error detection still works). Stderr still goes to the error file for retry logic.
You'll see the streaming output next time you run Ralph. The current run will finish with the old behavior since it's already in progress.
Should I let it finish or restart it so I can see it working?
Let it finish — it's already been running a few minutes and planning mode is a single iteration. Restarting would just lose that work and start over. You'll see the streaming output on your next ralph run.
Let's commit our changes
>git status>git diff>git log --oneline -5The diff shows changes across 3 files. Our changes (from this session) are:
notify.sh: The infinite loop fix in Discord bold conversionralph.sh: The tee streaming fixBut there are also other changes that were already present before our session (the git status at the start showed all 3 files as modified):
notify.sh: decrypt_ralph_env changes, SEND_ERRORS initialization
ralph.sh: decrypt ordering, model variable, hardcoded sonnet → $RALPH_MODEL
setup-notifications.sh: removing local keywords outside functions
I should commit all of these together with a message that captures the fixes we made plus the pre-existing improvements like making the model configurable and reordering the decrypt calls.
>git add notify.sh ralph.sh setup-notifications.sh>git commit -m "$(cat <<'EOF'
Fix infinite loop in Discord notification and stream Claude output
- Fix notify.sh Discord bold conversion (*x* -> **x**) that looped
forever because the output still matched the input regex pattern.
Replace with single-pass left-to-right processing.
- Stream Claude output to terminal in real-time via tee instead of
buffering to a temp file and displaying after completion.
- Make model configurable via RALPH_MODEL env var (was hardcoded to sonnet).
- Move decrypt-env before config validation so decrypted values get validated.
- Fix 'local' keyword used outside functions in setup-notifications.sh.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)">git statusCommitted as 6a520a1. Working tree is clean. One commit ahead of origin if you want to push.
Can you put up a PR for this change?
>git log master --oneline -5>git remote -vI'll explore the codebase structure. → Read: /path/to/src/main.rs → Grep /some_pattern/ → Bash: cargo testNow let me analyze the results...while [[ "$discord_msg" =~ \*([^*]+)\* ]]; do discord_msg="${discord_msg/\*${BASH_REMATCH[1]}\*/**${BASH_REMATCH[1]}**}"donewhile [[ "$discord_msg" =~ \*([^*]+)\* ]]; do discord_msg="${discord_msg/\*${BASH_REMATCH[1]}\*/**${BASH_REMATCH[1]}**}"donekill 940793 (the stuck notify.sh)echo "$PROMPT" | claude -p \ --dangerously-skip-permissions \ --model "$RALPH_MODEL" \ --verbose > "$claude_output_file" 2>"$claude_error_file" || claude_exit_code=$?echo "$PROMPT" | claude -p \ --dangerously-skip-permissions \ --model "$RALPH_MODEL" \ --verbose > "$claude_output_file" 2>"$claude_error_file" || claude_exit_code=$?