Ralph - Gemini CLI Edition

Ralph is an autonomous AI agent loop that runs Gemini CLI 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.

• Gemini CLI installed and authenticated
  • npm install -g gemini-chat-cli (or similar depending on distribution)
  • gemini login or GOOGLE_API_KEY set
• jq installed (brew install jq on macOS)
• A git repository for your project
• Python 3 installed (for the wrapper)

Copy the ralph files into your project:

# From your project root
mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/
cp /path/to/ralph/ralph_gemini.py scripts/ralph/
cp /path/to/ralph/prompt.md scripts/ralph/
chmod +x scripts/ralph/ralph.sh

Use a tool or manual process to create a prd.json file. See prd.json.example for the required format.

./scripts/ralph/ralph.sh [max_iterations]

Default is 10 iterations.

Ralph will:

1. Read the context (prd.json, progress.txt, prompt.md)
2. Spawn a gemini CLI instance using the Python wrapper.
3. Autonomous Execution: Gemini uses native tools (File Read/Write, Shell Execution) to:
   • Pick the next task.
   • Implement code changes.
   • Run tests/checks.
   • Commit changes using git.
4. Repeat until all stories pass or max iterations reached.

Ralph now runs in YOLO Mode, meaning the agent has full, unprompted access to:

• File System: Reading and writing files directly.
• Shell: executing git commands, running tests, etc.

Each iteration spawns a new Gemini context. The only memory between iterations is:

• Git history (commits from previous iterations)
• progress.txt (learnings and context)
• prd.json (which stories are done)

When all stories have passes: true, Ralph outputs RALPH_COMPLETE and the loop exits.

• Geoffrey Huntley's Ralph article
• Gemini CLI Documentation