diff --git a/AGENTS.md b/AGENTS.md index 9da9ecd1..d62c5f8d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ ## Overview -Ralph is an autonomous AI agent loop that runs AI coding tools (Amp or Claude Code) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context. +Ralph is an autonomous AI agent loop that runs AI coding tools (Amp, Claude Code, or Codex) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context. ## Commands @@ -18,11 +18,14 @@ cd flowchart && npm run build # Run Ralph with Claude Code ./ralph.sh --tool claude [max_iterations] + +# Run Ralph with Codex +./ralph.sh --tool codex [max_iterations] ``` ## Key Files -- `ralph.sh` - The bash loop that spawns fresh AI instances (supports `--tool amp` or `--tool claude`) +- `ralph.sh` - The bash loop that spawns fresh AI instances (supports `--tool amp`, `--tool claude`, or `--tool codex`) - `prompt.md` - Instructions given to each AMP instance - `CLAUDE.md` - Instructions given to each Claude Code instance - `prd.json.example` - Example PRD format @@ -41,7 +44,8 @@ npm run dev ## Patterns -- Each iteration spawns a fresh AI instance (Amp or Claude Code) with clean context +- Each iteration spawns a fresh AI instance (Amp, Claude Code, or Codex) with clean context - Memory persists via git history, `progress.txt`, and `prd.json` - Stories should be small enough to complete in one context window +- Completion should be checked from `prd.json` (`userStories[].passes`) rather than relying only on model output text - Always update AGENTS.md with discovered patterns for future iterations diff --git a/CLAUDE.md b/CLAUDE.md index f95bb927..1716c8b0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -89,10 +89,7 @@ If no browser tools are available, note in your progress report that manual brow ## Stop Condition -After completing a user story, check if ALL stories have `passes: true`. - -If ALL stories are complete and passing, reply with: -COMPLETE +Ralph checks `prd.json` after each iteration and stops automatically when all `userStories[].passes` values are `true`. If there are still stories with `passes: false`, end your response normally (another iteration will pick up the next story). diff --git a/README.md b/README.md index d79d8b62..836ac062 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ![Ralph](ralph.webp) -Ralph is an autonomous AI agent loop that runs AI coding tools ([Amp](https://ampcode.com) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code)) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context. Memory persists via git history, `progress.txt`, and `prd.json`. +Ralph is an autonomous AI agent loop that runs AI coding tools ([Amp](https://ampcode.com), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), or Codex) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context. Memory persists via git history, `progress.txt`, and `prd.json`. Based on [Geoffrey Huntley's Ralph pattern](https://ghuntley.com/ralph/). @@ -13,6 +13,7 @@ Based on [Geoffrey Huntley's Ralph pattern](https://ghuntley.com/ralph/). - One of the following AI coding tools installed and authenticated: - [Amp CLI](https://ampcode.com) (default) - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`npm install -g @anthropic-ai/claude-code`) + - Codex CLI (`codex`) - `jq` installed (`brew install jq` on macOS) - A git repository for your project @@ -28,7 +29,7 @@ mkdir -p scripts/ralph cp /path/to/ralph/ralph.sh scripts/ralph/ # Copy the prompt template for your AI tool of choice: -cp /path/to/ralph/prompt.md scripts/ralph/prompt.md # For Amp +cp /path/to/ralph/prompt.md scripts/ralph/prompt.md # For Amp or Codex # OR cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md # For Claude Code @@ -115,9 +116,12 @@ This creates `prd.json` with user stories structured for autonomous execution. # Using Claude Code ./scripts/ralph/ralph.sh --tool claude [max_iterations] + +# Using Codex +./scripts/ralph/ralph.sh --tool codex [max_iterations] ``` -Default is 10 iterations. Use `--tool amp` or `--tool claude` to select your AI coding tool. +Default is 10 iterations. Use `--tool amp`, `--tool claude`, or `--tool codex` to select your AI coding tool. Ralph will: 1. Create a feature branch (from PRD `branchName`) @@ -133,8 +137,8 @@ Ralph will: | File | Purpose | |------|---------| -| `ralph.sh` | The bash loop that spawns fresh AI instances (supports `--tool amp` or `--tool claude`) | -| `prompt.md` | Prompt template for Amp | +| `ralph.sh` | The bash loop that spawns fresh AI instances (supports `--tool amp`, `--tool claude`, or `--tool codex`) | +| `prompt.md` | Prompt template for Amp or Codex | | `CLAUDE.md` | Prompt template for Claude Code | | `prd.json` | User stories with `passes` status (the task list) | | `prd.json.example` | Example PRD format for reference | @@ -162,7 +166,7 @@ npm run dev ### Each Iteration = Fresh Context -Each iteration spawns a **new AI instance** (Amp or Claude Code) with clean context. The only memory between iterations is: +Each iteration spawns a **new AI instance** (Amp, Claude Code, or Codex) with clean context. The only memory between iterations is: - Git history (commits from previous iterations) - `progress.txt` (learnings and context) - `prd.json` (which stories are done) @@ -204,7 +208,7 @@ Frontend stories must include "Verify in browser using dev-browser skill" in acc ### Stop Condition -When all stories have `passes: true`, Ralph outputs `COMPLETE` and the loop exits. +When all stories have `passes: true` in `prd.json`, Ralph stops automatically after that iteration. No special output token is required from the agent. ## Debugging @@ -223,7 +227,7 @@ git log --oneline -10 ## Customizing the Prompt -After copying `prompt.md` (for Amp) or `CLAUDE.md` (for Claude Code) to your project, customize it for your project: +After copying `prompt.md` (for Amp or Codex) or `CLAUDE.md` (for Claude Code) to your project, customize it for your project: - Add project-specific quality check commands - Include codebase conventions - Add common gotchas for your stack @@ -237,3 +241,4 @@ Ralph automatically archives previous runs when you start a new feature (differe - [Geoffrey Huntley's Ralph article](https://ghuntley.com/ralph/) - [Amp documentation](https://ampcode.com/manual) - [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code) +- [Codex CLI documentation](https://developers.openai.com/codex/) diff --git a/prompt.md b/prompt.md index cdebe901..69904005 100644 --- a/prompt.md +++ b/prompt.md @@ -93,10 +93,7 @@ A frontend story is NOT complete until browser verification passes. ## Stop Condition -After completing a user story, check if ALL stories have `passes: true`. - -If ALL stories are complete and passing, reply with: -COMPLETE +Ralph checks `prd.json` after each iteration and stops automatically when all `userStories[].passes` values are `true`. If there are still stories with `passes: false`, end your response normally (another iteration will pick up the next story). diff --git a/ralph.sh b/ralph.sh index baff052a..01783f0b 100755 --- a/ralph.sh +++ b/ralph.sh @@ -1,6 +1,6 @@ #!/bin/bash # Ralph Wiggum - Long-running AI agent loop -# Usage: ./ralph.sh [--tool amp|claude] [max_iterations] +# Usage: ./ralph.sh [--tool amp|claude|codex] [max_iterations] set -e @@ -29,8 +29,8 @@ while [[ $# -gt 0 ]]; do done # Validate tool choice -if [[ "$TOOL" != "amp" && "$TOOL" != "claude" ]]; then - echo "Error: Invalid tool '$TOOL'. Must be 'amp' or 'claude'." +if [[ "$TOOL" != "amp" && "$TOOL" != "claude" && "$TOOL" != "codex" ]]; then + echo "Error: Invalid tool '$TOOL'. Must be 'amp', 'claude', or 'codex'." exit 1 fi SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" @@ -81,6 +81,22 @@ fi echo "Starting Ralph - Tool: $TOOL - Max iterations: $MAX_ITERATIONS" +check_prd_completion() { + local remaining_stories + + if [ ! -f "$PRD_FILE" ]; then + echo "Warning: Missing PRD file at $PRD_FILE. Treating as incomplete." + return 1 + fi + + if ! remaining_stories="$(jq '.userStories[] | select(.passes == false) | {id, title, passes}' "$PRD_FILE" 2>/dev/null)"; then + echo "Warning: Unable to parse $PRD_FILE for completion check. Treating as incomplete." + return 1 + fi + + [ -z "$remaining_stories" ] +} + for i in $(seq 1 $MAX_ITERATIONS); do echo "" echo "===============================================================" @@ -90,13 +106,17 @@ for i in $(seq 1 $MAX_ITERATIONS); do # Run the selected tool with the ralph prompt if [[ "$TOOL" == "amp" ]]; then OUTPUT=$(cat "$SCRIPT_DIR/prompt.md" | amp --dangerously-allow-all 2>&1 | tee /dev/stderr) || true - else + elif [[ "$TOOL" == "claude" ]]; then # Claude Code: use --dangerously-skip-permissions for autonomous operation, --print for output OUTPUT=$(claude --dangerously-skip-permissions --print < "$SCRIPT_DIR/CLAUDE.md" 2>&1 | tee /dev/stderr) || true + else + # Codex: run non-interactively with sandbox/approval bypass for autonomous operation. + PROMPT_CONTENT="$(cat "$SCRIPT_DIR/prompt.md")" + OUTPUT=$(codex exec --dangerously-bypass-approvals-and-sandbox "$PROMPT_CONTENT" 2>&1 | tee /dev/stderr) || true fi - # Check for completion signal - if echo "$OUTPUT" | grep -q "COMPLETE"; then + # Check completion based on PRD stories. + if check_prd_completion; then echo "" echo "Ralph completed all tasks!" echo "Completed at iteration $i of $MAX_ITERATIONS"