Ralph TUI - AI Agent Loop Orchestrator
Overview
Ralph TUI is a terminal-based AI agent loop orchestrator that autonomously manages AI coding agents through task backlogs, executing them in coordinated loops until completion. It bridges the gap between single-pass AI agents and sustained, autonomous development workflows by maintaining persistent execution cycles with intelligent task selection and error handling.
Repository: github.com/subsy/ralph-tui
Website: ralph-tui.com
License: MIT
Stars: 1.6k+ | Contributors: 17+
Latest Release: v0.6.0 (Theme Improvements, Jan 2026)
Core Concepts
The Ralph Loop
Ralph operates through a continuous four-step execution cycle that repeats until all tasks are complete:
- SELECT - Picks highest-priority task from issue tracker based on priority and dependencies
- PROMPT - Generates smart prompts from Handlebars templates with minimal relevant context injection
- EXECUTE - Runs autonomous AI coding agent with real-time progress monitoring
- EVALUATE - Analyzes output to determine completion status and identifies next actions
The loop continues until all tasks are marked complete or the agent determines no further work is needed.
Design Philosophy
Ralph’s design emphasizes that the orchestrator is a thin coordination layer, not a platform—agents are smart and should be allowed to do the work. The tool is intentionally lightweight and gets out of the way, letting AI agents handle implementation details while Ralph manages flow and dependencies.
Designed to be faithful to Geoffrey Huntley’s original Ralph Wiggum loop concept.
Execution Modes
Traditional Mode
A simple iterative loop where Ralph repeats until the completion promise is output. Best for quick tasks and minimal configuration.
Hat-Based Mode
Enables specialized personas with event-driven coordination through a “hat system”:
- Ralph serves as the constant coordinator (cannot be removed)
- Additional loops automatically spawn into isolated worktrees with separate event systems, tasks, and scratchpads
- Memories are shared and symlinked back to main repository
- Dedicated merge-ralph instances integrate changes from parallel executions
Designed for complex multi-step processes and parallel task execution with isolated contexts while maintaining shared knowledge.
Key Features
Planning Phase
AI-Driven PRD Generation
- Interactively create comprehensive Product Requirements Documents through natural conversation with AI
- Natural language feature descriptions with clarifying questions
- Structured user stories with acceptance criteria
- Automatic scope boundary definition
Atomic Task Creation
- Transform PRDs into dependency-aware, right-sized tasks
- Automatic dependency graph generation
- Context-window-aware task sizing
- Priority-based execution ordering
- Quality gates baked into each task
Task Management
Multiple Task Trackers
prd.json- Simple JSON-based task files- Beads - Git-backed issue tracker with dependency awareness
- Beads-BV - Graph-aware task prioritization
- Automatic dependency resolution and parallel execution scheduling
Intelligent Task Routing
- Dependency awareness prevents running tasks before blockers complete
- Priority-based selection logic
- Task graph analysis for optimal execution order
- Cross-iteration context tracking
Agent Support
Works with multiple AI coding assistants:
- Claude Code
- OpenCode
- Factory Droid
- Gemini CLI
- Codex
- Kiro CLI
- Custom agents via plugin architecture
Execution Control
Real-time TUI Dashboard
- Elegant terminal interface for monitoring
- View current execution status and active task
- Agent name and model display
- Tracker source information
- Git branch status with dirty indicators
- Sandbox status and auto-commit settings
- Live output streaming of agent code generation
Session Persistence
- Pause/resume at any time without losing state
- Automatic state saving
- Survives crashes and interruptions
- Session recovery with intelligent context recovery
- Iteration limits for safe long-running sessions
Keyboard Controls
s- Start executionp- Pause/Resumed- Toggle dashboardT- Toggle subagent tree panelt- Cycle subagent detail levelo- Cycle right panel views,- Open settingsC- Open config viewer?- Show helpq- Quit
Advanced Tracing & Debugging
Subagent Tracing
- Full visibility into nested agent calls
- Real-time execution path tracing
- Complete decision tree visibility
- Trace and debug nested agent calls in real-time
Cross-Iteration Context
- Automatic progress tracking between tasks
- Intelligent context management
- Minimal relevant context injection
Remote Instance Management
Multi-Machine Control
- Monitor and control ralph-tui instances running on different machines
- Centralized control from single TUI
- Tab-based navigation between local and remote instances
- VPS servers, CI/CD environments, development boxes support
Security Model
- Two-tier token system:
- Server Token (90 days) - Initial authentication, stored on disk
- Connection Token (24 hours) - Session authentication, auto-refreshed
- Binds to localhost (127.0.0.1) without token configuration
- Binds to all interfaces (0.0.0.0) with token
- All connections require authentication
- Complete audit logging (
~/.config/ralph-tui/audit.log) - Tokens shown only once at generation time
Connection Resilience
- Auto-reconnect with exponential backoff (1s to 30s, max 10 retries)
- Silent retries for first 3 attempts, then toast notifications
- Status indicators (● connected, ◐ connecting, ⟳ reconnecting, ○ disconnected)
- Latency and connection duration metrics in tab bar
Remote Configuration
- Push configuration to remote instances
- Backup existing configs before overwriting
- Auto-migration to install skills/templates
- Scope selection (global or project-level)
Customization
Prompt Templates
- Reusable Handlebars templates for consistent, high-quality prompts
- Context injection strategies
- Custom template directory support
- Skills templates for PRD/task generation
Custom Themes
- Bundled themes:
bright-theme.json,high-contrast-theme.json - Full theme schema support
- Custom color themes via
--themeoption
Skills Integration
- Use slash commands in your agent (e.g.,
/ralph-create-prd) - Reference source files with
@filename - Install skills using add-skill
- Custom skills directory support (must contain
SKILL.md)
CLI Commands
| Command | Description |
|---|---|
ralph-tui | Launch interactive TUI |
ralph-tui run [options] | Start Ralph execution |
ralph-tui resume | Resume interrupted session |
ralph-tui status | Check session status |
ralph-tui logs | View iteration output logs |
ralph-tui setup | Run interactive project setup |
ralph-tui create-prd | Create new PRD interactively |
ralph-tui convert | Convert PRD to tracker format |
ralph-tui config show | Display merged configuration |
ralph-tui template show | Display current prompt template |
ralph-tui plugins agents | List available agent plugins |
ralph-tui plugins trackers | List available tracker plugins |
ralph-tui run --listen | Run with remote listener enabled |
ralph-tui remote <cmd> | Manage remote server connections |
ralph-tui push-config | Push config to remote instances |
Installation
# Install globally via Bun
bun install -g ralph-tui
# Initialize for project
ralph-tui init
# Or combined
bun install -g ralph-tui && ralph-tui init Technology Stack
- Runtime: Bun - Fast JavaScript runtime
- UI Framework: OpenTUI - Terminal UI framework
- Templates: Handlebars - Prompt templating
- Language: TypeScript (92.6% of codebase)
- Build: Modern tooling with high test coverage requirements (>50%)
Configuration
Configuration files:
~/.config/ralph-tui/config.toml- Global configuration.ralph-tui/config.toml- Project-level configuration~/.config/ralph-tui/remote.json- Remote server tokens~/.config/ralph-tui/remotes.toml- Remote configurations~/.config/ralph-tui/audit.log- Remote action audit log~/.config/ralph-tui/listen.pid- Daemon PID file
Configuration merging: Project config overrides global config.
Use Cases
Autonomous Development
Run AI agents hands-free through entire feature implementations, with Ralph managing task selection and orchestration.
Multi-Agent Workflows
Coordinate multiple agents on different tasks simultaneously using hat-based mode with isolated worktrees.
Large Codebase Management
Handle complex projects with dependency-aware task sequencing and intelligent context window management.
CI/CD Integration
Control ralph-tui instances remotely from CI/CD pipelines with audit logging and secure token management.
Interactive Planning
Create structured PRDs and task breakdowns collaboratively with AI before autonomous execution.
Workflow Example
# 1. Initialize project
ralph-tui setup
# 2. Create PRD interactively
ralph-tui create-prd
# 3. Convert to task tracker
ralph-tui convert
# 4. Run autonomous execution
ralph-tui run
# 5. Monitor from another location
ralph-tui remote add prod <host> <port> <token> Integration with Other Tools
- Beads - Git-backed issue tracking with dependency awareness (primary integration)
- Claude Code - Full support for autonomous coding tasks
- Git - Native repository integration with branch management
- Worktrees - Support for isolated parallel execution contexts
- MCP Agent Mail - Potential for agent-to-agent communication (via Beads ecosystem)
Project Status
- Maturity: Active development, rapid iteration (~3 days since last commit)
- Community: 17+ contributors, healthy PR activity
- Code Quality: Strong test coverage requirements (>50% on new code)
- Documentation: Comprehensive docs site with guides and examples
- Versioning: Semantic versioning with regular releases
Related Concepts
- Steve Yegge - Created Beads which Ralph integrates with
- Agent Mail - MCP Agent Mail for agent-to-agent messaging (complements Ralph + Beads)
- Vibe Coding - Autonomous AI development workflow pattern
- Gas Town - Orchestration system that inspired Ralph’s design patterns
Resources
- Official Site: ralph-tui.com
- GitHub: github.com/subsy/ralph-tui
- Docs: ralph-tui.com/docs
- Quick Start: ralph-tui.com/docs/getting-started/quick-start
- CLI Reference: ralph-tui.com/docs/cli/overview
- Contributing: CONTRIBUTING.md
Sources
- Ralph TUI Official Website - https://ralph-tui.com/
- Ralph TUI GitHub Repository - https://github.com/subsy/ralph-tui
- Ralph TUI Documentation - https://ralph-tui.com/docs
- Perplexity AI Research on Ralph TUI Architecture and Features
- Ralph TUI GitHub README and Contributing Guidelines