Ralph TUI

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, Factory Droid, Gemini CLI, Codex, Kiro CLI) to your task tracker and runs them in an autonomous loop, completing tasks one-by-one with intelligent selection, error handling, and full visibility.

Quick Start

# 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.json

That's it! Ralph will work through your tasks autonomously.

Documentation

ralph-tui.com - Full documentation, guides, and examples.

Quick Links

• 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

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐   │
│   │  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.

Features

• Task Trackers: prd.json (simple), Beads (git-backed with dependencies)
• AI Agents: Claude Code, OpenCode, Factory Droid, Gemini CLI, Codex, Kiro CLI
• 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
• Flexible Skills: Use PRD/task skills directly in your agent or via the TUI
• Remote Instances: Monitor and control ralph-tui running on multiple machines from a single TUI

CLI Commands

| 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 | | ralph-tui run --listen | Run with remote listener enabled | | ralph-tui remote <cmd> | Manage remote server connections |

Common Options

# 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

# Run agent in isolated sandbox (bwrap on Linux, sandbox-exec on macOS)
# Requires bwrap to be installed and on PATH (Linux) or uses built-in sandbox-exec (macOS)
ralph-tui run --sandbox

Create PRD Options

# 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

TUI Keyboard Shortcuts

| Key | Action | |-----|--------| | s | Start execution | | p | Pause/Resume | | d | Toggle dashboard | | T | Toggle subagent tree panel (Shift+T) | | t | Cycle subagent detail level | | o | Cycle right panel views | | , | Open settings (local tab only) | | C | Open read-only config viewer (Shift+C, works on local and remote tabs) | | q | Quit | | ? | Show help | | 1-9 | Switch to tab 1-9 (remote instances) | | [ / ] | Previous/Next tab | | a | Add new remote instance | | e | Edit current remote (when viewing remote tab) | | x | Delete current remote (when viewing remote tab) |

Dashboard (d key): Toggle a status panel showing:

• Current execution status and active task
• Agent name and model (e.g., claude-code, anthropic/claude-sonnet)
• Tracker source (e.g., prd, beads)
• Git branch with dirty indicator (repo:branch*)
• Sandbox status (🔒 enabled, 🔓 disabled) with mode
• Auto-commit setting (✓ auto, ✗ manual)
• Remote connection info (when viewing remote tabs)

See the full CLI reference for all options.

Using Skills Directly in Your Agent

Install ralph-tui skills to your agent using add-skill:

# Install all skills to all detected agents globally
bunx add-skill subsy/ralph-tui --all

# Install to a specific agent
bunx add-skill subsy/ralph-tui -a claude-code -g -y

# Or use the ralph-tui wrapper (maps agent IDs automatically)
ralph-tui skills install
ralph-tui skills install --agent claude

Use these slash commands in your agent:

/ralph-tui-prd           # Create a PRD interactively
/ralph-tui-create-json   # Convert PRD to prd.json
/ralph-tui-create-beads  # Convert PRD to Beads issues

This lets you create PRDs while referencing source files (@filename) and using your full conversation context—then use ralph-tui run for autonomous execution.

Custom Skills Directory

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-skill

Skills must be folders inside skills_dir containing a SKILL.md file.

Remote Instance Management

Control multiple ralph-tui instances running on different machines (VPS servers, CI/CD environments, development boxes) from a single TUI.

┌─────────────────────────────────────────────────────────────────┐
│  LOCAL [1]│ ● prod [2]│ ◐ staging [3]│ ○ dev [4]│      +       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   Your local TUI can connect to and control remote instances    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Start: Remote Control

On the remote machine (server):

# Start ralph with remote listener enabled
ralph-tui run --listen --prd ./prd.json

# First run generates a secure token - save it!
# ═══════════════════════════════════════════════════════════════
#                    Remote Listener Enabled
# ═══════════════════════════════════════════════════════════════
#   Port: 7890
#   New server token generated:
#   OGQwNTcxMjM0NTY3ODkwYWJjZGVmMDEyMzQ1Njc4OQ
#   ⚠️  Save this token securely - it won't be shown again!
# ═══════════════════════════════════════════════════════════════

On your local machine (client):

# Add the remote server
ralph-tui remote add prod server.example.com:7890 --token OGQwNTcxMjM0NTY3...

# Test the connection
ralph-tui remote test prod

# Launch TUI - you'll see tabs for local + remote instances
ralph-tui

Remote Listener Commands

Recommended: Use run --listen (runs engine with remote access):

# Start with remote listener on default port (7890)
ralph-tui run --listen --prd ./prd.json

# Start with custom port
ralph-tui run --listen --listen-port 8080 --epic my-epic

Token management:

# Rotate authentication token (invalidates old token immediately)
ralph-tui run --listen --rotate-token --prd ./prd.json

# View remote listener options
ralph-tui run --help

Remote Configuration Commands

# Add a remote server
ralph-tui remote add <alias> <host:port> --token <token>

# List all