feat: enhance ralph.sh with better UX and flexibility #13
Conversation
- Add --tool flag to ralph.sh (amp|claude, defaults to amp)
- Update documentation in README.md and AGENTS.md
- Update flowchart to be tool-agnostic ("AI picks a story" vs "Amp picks a story")
- Add .claude/ to .gitignore
Usage: ./ralph.sh --tool claude [max_iterations]
used CLAUDE.md
- Add 'opencode' as a valid --tool option alongside amp and claude - Embed agent prompt directly in ralph.sh via generate_prompt() function - Conditionally include AMP thread URL only when using amp tool - Remove prompt.md (no longer needed) - Update AGENTS.md to document the new tool option
- Remove SCRIPT_DIR, use paths relative to current working directory - Add validation with helpful error if prd.json not found - Add source field to prd.json format to track original PRD file - Update agent prompt to read source PRD for full context
Updated Ralph to use jq for extracting and updating user stories instead of reading/writing entire PRD files. Changes: - Use jq to extract only the next story: min_by(.priority) on incomplete stories - Use jq + sponge for in-place PRD updates when marking stories complete - Added validation checks for jq and sponge availability - Updated README prerequisites with installation instructions for both tools Benefits: 1. More efficient: Uses jq to extract only the next story instead of loading entire PRD 2. Safer updates: The jq + sponge pattern updates the PRD in-place without race conditions 3. Better error handling: Script validates both jq and sponge are installed before running 4. Clear documentation: README now clearly lists all required utilities with installation commands Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
Enhances ralph.sh to use the 'type' command for tool existence checks, which detects aliases, shell functions, and executables. Adds fallback support for local Claude installations at ~/.claude/local/claude when claude is not in PATH. Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
…ed progress header - Added '--' separator to pass additional arguments to the underlying tool - Enhanced progress.txt header to include tool name, tool args, and source PRD - Created init_progress_header() helper function to centralize header generation - Updated help documentation with examples of passing tool arguments - Progress file now shows full context: tool, args, and source PRD file Examples: ralph.sh --tool claude -- --model opus ralph.sh 15 -- --verbose Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
There was a problem hiding this comment.
Pull request overview
This PR enhances the Ralph autonomous AI agent loop to support multiple AI coding tools (Amp, Claude Code, OpenCode) instead of being hardcoded to Amp only. It improves developer experience with better CLI arguments, help documentation, and the ability to run Ralph from any directory with a prd.json file.
Changes:
- Added multi-tool support with
--toolflag (amp, claude, opencode) - Enhanced CLI with
--helpand--stopflags, plus passthrough arguments support - Embedded agent prompt directly in ralph.sh instead of reading from external files
- Added support for source PRD traceability via prd.json's
sourcefield - Updated all documentation to reflect multi-tool support
Reviewed changes
Copilot reviewed 7 out of 8 changed files in this pull request and generated 13 comments.
Show a summary per file
| File | Description |
|---|---|
| ralph.sh | Complete rewrite adding multi-tool support, embedded prompt generation, improved argument parsing, tool detection, and stop signal handling |
| skills/ralph/SKILL.md | Updated to document the new source field in prd.json for PRD traceability |
| README.md | Updated installation instructions and usage examples for multi-tool support |
| AGENTS.md | Updated documentation to reflect multi-tool capability and embedded prompt |
| CLAUDE.md | Updated prompt template with jq commands and relaxed browser testing requirements |
| flowchart/src/App.tsx | Changed "Amp" references to generic "AI" to reflect tool-agnostic approach |
| flowchart/index.html | Updated page title to be tool-agnostic |
| .gitignore | Added .claude/ directory to gitignore |
Comments suppressed due to low confidence (2)
CLAUDE.md:15
- Same issue as in ralph.sh - the jq command placeholder "STORY-ID" in step 9 needs clarification that it should be replaced with the actual story identifier.
CLAUDE.md:88 - The CLAUDE.md file has removed the AMP-specific thread URL line (line 23 in the old version), but the instructions at lines 82-88 still reference browser testing via "MCP" (Model Context Protocol), which may not be universally available. The change from "Required for Frontend Stories" to "If Available" is good, but the instructions should clarify what "browser testing tools configured (e.g., via MCP)" means or provide alternatives for users without MCP access.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
I tested with this version last night on a fairly large PRD. I used amp on some iterations then after my daily allowance was consumed I switched to claude. I also ran a test using the original version that does not re-include the original PRD for context and then had a model compare the two commits produced by each. The model concluded that the "After" version that was created with the original PRD in context was superior. I noticed that although my PRD is very detailed and includes some "soft context" (the PRD was for generating detailed skills) the prd.json file was lacking a lot of this so I'm honestly surprised that it works very well without reading the original PRD for complex tasks? Anyway, I think it makes sense that each instance reads the original PRD and it's not that many tokens - still way better than one-shotting the entire thing. If you disagree, perhaps a flag could be added like '--skip-prd' to skip it when you feel like prd.json already has sufficient context. 
|
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Copilot <[email protected]>
- Agent now performs cleanup commit after all stories complete - Removes prd.json, progress.txt, .last-branch, and source PRD file - Cleanup commit can be reverted if needed - Add .agents/ralph.md for project-local prompt templates - Prompt priority: --custom-prompt > .agents/ralph.md > embedded default - Update help text, prompt-template.md, and README with documentation - Update completion message to inform user about cleanup
- Recommend installing ralph.sh to PATH as primary method - Add curl-based installation for ralph.sh and skills - Update 'Run Ralph' section to be path-agnostic - Move project-specific copy to Option 3 as alternative
When Ralph completes all stories and removes prd.json via cleanup commit, subsequent iterations now exit immediately without invoking the AI tool. This saves significant tokens when max_iterations is set higher than needed.
…ations - Add timing-based failure detection: iterations < 4s are flagged as failures - Exit after 5 consecutive quick failures to prevent rate limiting - Add 3s sleep between failures for backoff - Increase default max_iterations from 10 to 50 (safe with early exit optimization) - Update help text to document failure handling - Reset failure counter on successful iterations This catches configuration errors (invalid models, missing permissions) early while preventing runaway loops that could trigger rate limits.
- Add --eject-prompt flag to generate .agents/ralph.md from embedded prompt - Remove prompt-template.md to maintain single source of truth - Update help text with sample prompts in GETTING STARTED section - Simplify CUSTOMIZING THE PROMPT instructions to use --eject-prompt - Skip prd.json validation when using --eject-prompt flag
|
@colinmollenhour Thank you for taking time to work on this. Unfortunately I'm going to close with comment. The reason is I'd like to keep this repo as simple as possible. The flags you've added are helpful, but make it harder for people to understand. I'm sure it's working great for you though, and that's fab. |
|
No problem, looks like you're getting hammered with PRs so I get it. 😄 |
3 participants
Summary
Improves ralph.sh with better developer experience and more flexible configuration.
Changes
--helpflag - Usage info with visual flow diagram--stopflag - Gracefully interrupt Ralph between iterations--toolflag - Still uses amp by default, but adds support for OpenCode and Claude Code--tool-pathflag - Specify explicit path to tool executable (fixes local Claude detection issue)sourcefield from prd.json for full contexttypefor aliases/functions + local Claude fallback--(e.g.,ralph.sh -- --model opus)ralph.shis now a fully contained single file that you can just drop into your path one time--custom-promptflag - Override the embedded prompt with your own.agents/ralph.mdsupport - Project-local prompt templates (auto-detected)--eject-promptflag - Creates the.agents/ralph.mdfile so the user can modify it to their likingAcknowledgments
Built on top of Claude Code support originally contributed by @denen99 in #2.