AI Agent Loop Orchestrator - A terminal UI for orchestrating AI coding agents to work through task lists autonomously.
Ralph TUI connects your AI coding assistant (Claude Code, OpenCode) to your task tracker and runs them in an autonomous loop, completing tasks one-by-one with intelligent selection, error handling, and full visibility.
# Install
bun install -g ralph-tui
# Setup your project
cd your-project
ralph-tui setup
# Create a PRD with AI assistance
ralph-tui create-prd --chat
# Run Ralph!
ralph-tui run --prd ./prd.jsonThat's it! Ralph will work through your tasks autonomously.
ralph-tui.com - Full documentation, guides, and examples.
- Quick Start Guide - Get running in 2 minutes
- Installation - All installation options
- CLI Reference - Complete command reference
- Configuration - Customize Ralph for your workflow
- Troubleshooting - Common issues and solutions
┌─────────────────────────────────────────────────────────────────┐
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 1. SELECT │────▶│ 2. BUILD │────▶│ 3. EXECUTE │ │
│ │ TASK │ │ PROMPT │ │ AGENT │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ▲ │ │
│ │ ▼ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ 5. NEXT │◀────────────────────────│ 4. DETECT │ │
│ │ TASK │ │ COMPLETION │ │
│ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Ralph selects the highest-priority task, builds a prompt, executes your AI agent, detects completion, and repeats until all tasks are done.
- Task Trackers: prd.json (simple), Beads (git-backed with dependencies)
- AI Agents: Claude Code, OpenCode
- Session Persistence: Pause anytime, resume later, survive crashes
- Real-time TUI: Watch agent output, control execution with keyboard shortcuts
- Subagent Tracing: See nested agent calls in real-time
- Cross-iteration Context: Automatic progress tracking between tasks
| Command | Description |
|---|---|
ralph-tui |
Launch the interactive TUI |
ralph-tui run [options] |
Start Ralph execution |
ralph-tui resume |
Resume an 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 a 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 |
# Run with a PRD file
ralph-tui run --prd ./prd.json
# Run with a Beads epic
ralph-tui run --epic my-epic-id
# Override agent or model
ralph-tui run --agent claude --model sonnet
ralph-tui run --agent opencode --model anthropic/claude-3-5-sonnet
# Limit iterations
ralph-tui run --iterations 5
# Run headless (no TUI)
ralph-tui run --headless# Create a PRD with AI assistance (default chat mode)
ralph-tui create-prd
ralph-tui prime # Alias
# Use a custom PRD skill from skills_dir
ralph-tui create-prd --prd-skill my-custom-skill
# Override agent
ralph-tui create-prd --agent claude
# Output to custom directory
ralph-tui create-prd --output ./docs| Key | Action |
|---|---|
s |
Start execution |
p |
Pause/Resume |
d |
Toggle dashboard |
i |
Toggle iteration history |
u |
Toggle subagent tracing |
q |
Quit |
? |
Show help |
See the full CLI reference for all options.
You can configure a custom skills_dir in your config file to use custom PRD skills:
# In .ralph-tui/config.toml or ~/.config/ralph-tui/config.toml
skills_dir = "/path/to/my-skills"
# Then use custom skills
ralph-tui create-prd --prd-skill my-custom-skillSkills must be folders inside skills_dir containing a SKILL.md file.
git clone https://github.com/subsy/ralph-tui.git
cd ralph-tui
bun install
bun run devbun run build # Build the project
bun run typecheck # Type check (no emit)
bun run lint # Run linter
bun run lint:fix # Auto-fix lint issuesralph-tui/
├── src/
│ ├── cli.tsx # CLI entry point
│ ├── commands/ # CLI commands (run, resume, status, logs, etc.)
│ ├── config/ # Configuration loading and validation (Zod schemas)
│ ├── engine/ # Execution engine (iteration loop, events)
│ ├── interruption/ # Signal handling and graceful shutdown
│ ├── logs/ # Iteration log persistence
│ ├── plugins/
│ │ ├── agents/ # Agent plugins (claude, opencode)
│ │ │ └── tracing/ # Subagent tracing parser
│ │ └── trackers/ # Tracker plugins (beads, beads-bv, json)
│ ├── session/ # Session persistence and lock management
│ ├── setup/ # Interactive setup wizard
│ ├── templates/ # Handlebars prompt templates
│ ├── chat/ # AI chat mode for PRD creation
│ ├── prd/ # PRD generation and parsing
│ └── tui/ # Terminal UI components (OpenTUI/React)
│ └── components/ # React components
├── skills/ # Bundled skills for PRD/task creation
│ ├── ralph-tui-prd/
│ ├── ralph-tui-create-json/
│ └── ralph-tui-create-beads/
├── website/ # Documentation website (Next.js)
└── docs/ # Images and static assets
- Bun - JavaScript runtime
- OpenTUI - Terminal UI framework
- React - Component model for TUI
- Handlebars - Prompt templating
- Zod - Configuration validation
See CLAUDE.md for detailed development guidelines.
Thanks to Geoffrey Huntley for the original Ralph Wiggum loop concept.
MIT License - see LICENSE for details.