feat: user hints injection + robustness improvements

[jamoptimus]

Summary

This PR adds robustness improvements to ralph.sh and introduces a user hints injection feature for interactive control during autonomous runs.

Changes

New Feature: User Hints Injection

• Add .ralph-hints.txt file support for injecting context into Ralph iterations
• Hints are prepended to the prompt and file is cleaned up after reading
• Works with both amp and claude tools
• Enables external control (like Discord bots) to guide Ralph mid-run

Robustness Improvements

• Tool validation: Check jq/amp/claude exist before running
• Consecutive error tracking: Stop after 3 consecutive tool failures
• Exit code capture: Replace || true with explicit error handling
• Error logging: Log failures to progress.txt for debugging
• Atomic file handling: Rename-before-read pattern for hints file
• Proper quoting: Quote arithmetic variables and use parameter expansion
• Pipeline error handling: Add set -o pipefail for proper exit codes

Minor Fixes

• Use printf instead of echo for hints (handles special characters)
• Add error handling for archive mkdir/cp operations
• Validate SCRIPT_DIR determination

Testing

These changes have been tested with JamBot's Ralph integration, running multiple autonomous coding sessions with hint injection working correctly.

---

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.5 noreply@anthropic.com

[greptile-apps]

Greptile Overview

Greptile Summary

Added user hints injection feature (.ralph-hints.txt) and comprehensive robustness improvements to the Ralph autonomous agent loop. The hints feature enables external systems to inject context mid-run using an atomic rename-before-read pattern. Robustness enhancements include tool validation at startup, consecutive error tracking with a 3-failure threshold, proper exit code capture, error logging to progress.txt, and set -o pipefail for pipeline error handling.

Key changes:

• User hints injection via .ralph-hints.txt with atomic file handling
• Tool validation for jq, amp, and claude before execution
• Consecutive error tracking stops execution after 3 consecutive failures
• Proper exit code capture replaces previous || true pattern
• Error logging to progress.txt for debugging
• Parameter expansion for string manipulation (${LAST_BRANCH#ralph/})
• Fixed flowchart edge initialization bug (removed incorrect index < 0 condition)

The changes improve reliability and enable external control of Ralph during autonomous runs.

Confidence Score: 4/5

• Safe to merge with minor considerations about error threshold tuning
• Code implements solid error handling patterns, atomic file operations, and proper shell scripting practices. The consecutive error threshold of 3 is reasonable but may need adjustment based on real-world usage. All variables are properly quoted and exit codes are captured correctly.
• No files require special attention - changes are well-structured and tested

Important Files Changed

Filename	Overview
ralph.sh	Added user hints injection feature, tool validation, consecutive error tracking, and improved error handling throughout
flowchart/src/App.tsx	Fixed edge initialization logic by removing incorrect condition index < 0 that prevented edges from appearing

Sequence Diagram

sequenceDiagram
    participant User as External System
    participant RalphScript as ralph.sh
    participant HintsFile as .ralph-hints.txt
    participant AI as AI Tool
    
    User->>HintsFile: Write hints for guidance
    
    RalphScript->>RalphScript: Start iteration loop
    RalphScript->>HintsFile: Check if file exists
    
    alt Hints file exists
        RalphScript->>HintsFile: Atomic mv to .consumed
        RalphScript->>HintsFile: Read .consumed file
        RalphScript->>HintsFile: Delete .consumed
        RalphScript->>RalphScript: Prepend hints to prompt
    end
    
    RalphScript->>AI: Execute with prompt
    AI-->>RalphScript: Return output and exit code
    
    alt Tool error
        RalphScript->>RalphScript: Increment ERROR_COUNT
        RalphScript->>RalphScript: Log to progress.txt
        alt ERROR_COUNT >= 3
            RalphScript->>RalphScript: Stop execution
        end
    else Minimal output
        RalphScript->>RalphScript: Increment ERROR_COUNT
        alt ERROR_COUNT >= 3
            RalphScript->>RalphScript: Stop execution
        end
    else Success
        RalphScript->>RalphScript: Reset ERROR_COUNT
        alt Output has COMPLETE signal
            RalphScript->>RalphScript: Exit with success
        else More iterations needed
            RalphScript->>RalphScript: Continue loop
        end
    end

Loading

[greptile-apps]

_{2 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Missing $ before ERROR_COUNT in comparison

Suggested change

	if [ $ERROR_COUNT -ge $MAX_CONSECUTIVE_ERRORS ]; then
	if [ "$ERROR_COUNT" -ge "$MAX_CONSECUTIVE_ERRORS" ]; then

Prompt To Fix With AI

This is a comment left during a code review.
Path: ralph.sh
Line: 166:166

Comment:
Missing `$` before `ERROR_COUNT` in comparison

```suggestion
    if [ "$ERROR_COUNT" -ge "$MAX_CONSECUTIVE_ERRORS" ]; then
```

How can I resolve this? If you propose a fix, please make it concise.

[jamoptimus]

Fixed the variable quoting issue flagged in review - pushed f33c480. Thanks Greptile!

[snarktank]

@greptile can you do a final review? The author fixed the variable quoting issue you flagged.