# Ralph TUI Ralph TUI is an AI Agent Loop Orchestrator; a [[Terminal User Interface (TUI)]] for running AI coding agents autonomously through task lists. It automates the cycle of selecting tasks, building prompts, running AI agents, and detecting completion. Instead of manually copying task details into [[Claude Code]], OpenCode, or other AI coding assistants, Ralph does it in a continuous loop. It connects your AI assistant to your task tracker ([[Beads]], prd.json) and completes tasks one-by-one with intelligent selection, error handling, and full visibility. ## Key Features - **Autonomous execution**: Runs AI agents in a loop until all tasks complete - **Session persistence**: Pause anytime, resume later, survive crashes - **Real-time TUI**: Watch agent output as it happens - **Subagent tracing**: See nested agent calls - **Cross-iteration context**: Automatic progress tracking between tasks - **Remote instances**: Monitor multiple machines from a single TUI - **Plugin architecture**: Integrate different AI agents and task tracking systems ## How It Works 1. Ralph reads tasks from your task source ([[Beads]], prd.json) 2. Selects the next available task intelligently 3. Builds a prompt with task details and context 4. Runs your AI coding agent ([[Claude Code]], OpenCode, [[Gemini CLI]], Codex, etc.) 5. Detects completion via token (`<promise>COMPLETE</promise>`) 6. Moves to the next task automatically ## Supported AI Agents - [[Claude Code]] - OpenCode - Factory Droid - [[Gemini CLI]] - Codex - Kiro CLI ## Supported Task Sources - [[Beads]] (via [[Beads Viewer]]) - prd.json files - Custom sources via plugins ## Installation ```bash # Install globally bun install -g ralph-tui # Setup your project ralph-tui setup # Create a PRD with AI assistance ralph-tui create-prd --chat # Run autonomously ralph-tui run --prd ./prd.json ``` ## The Ralph Wiggum Technique Ralph TUI is named after The Simpsons character Ralph Wiggum; known for being clueless yet relentlessly persistent. The "[[Ralph Loop]]" embodies this spirit: an AI coding loop that stubbornly iterates on tasks, failing repeatedly but never giving up until it finally succeeds. Also known as the [[Ralph Wiggum Technique]]. This approach recognizes that AI agents may not succeed on the first try, but with persistence and good error handling, they can complete complex multi-step tasks autonomously. ## Architecture Ralph TUI replaces shell-script-based agent loops with a structured execution engine that supports: - Pause/resume functionality - Crash recovery - Comprehensive iteration logging - Real-time observability - Plugin-based extensibility ## References - https://ralph-tui.dev - https://github.com/subsy/ralph-tui - https://ralph-tui.com/docs/getting-started/introduction ## Related - [[Terminal User Interface (TUI)]] - [[AI Agents]] - [[AI Agent Swarms]] - [[Beads]] - [[Beads Viewer]] - [[Claude Code]] - [[Command Line Interface (CLI)]] - [[Ralph Loop]] - [[Ralph Wiggum Technique]] - [[Ralph Wiggum]]