RalphTUI

Quick Start

Get up and running with Ralph TUI in 2 minutes using JSON mode - no external dependencies required.

2-Minute Quickstart

The fastest way to get started is with JSON mode - no external dependencies required! You'll have Ralph TUI running autonomously in just a few steps.

INFO

JSON mode uses a simple prd.json file for task tracking. It's perfect for getting started quickly without setting up external tools.

Install Ralph TUI

Install Ralph TUI globally using bun:

Bash
bun install -g ralph-tui
INFO

Ralph TUI requires Bun as its runtime. If you don't have Bun installed, see the Installation guide.

Setup Your Project

Navigate to your project and run the setup wizard:

Bash
cd your-project
ralph-tui setup

The interactive wizard will:

  • Detect installed agents (Claude Code, OpenCode, Factory Droid)
  • Create a .ralph-tui/config.toml configuration file
  • Install bundled skills for PRD creation and task conversion
  • Optionally detect existing trackers

Create a PRD

Use the AI-powered PRD creator to define your feature:

Bash
ralph-tui create-prd --chat

The AI will ask about your feature goals and requirements, then generate:

  • A PRD markdown file (./tasks/prd-<feature>.md)
  • A task file (./prd.json) ready for execution
INFO

Answer the AI's questions about your feature. When done, you'll be prompted to create tasks automatically.

Run Ralph

Start the autonomous execution loop:

Bash
ralph-tui run --prd ./prd.json

Ralph will now:

  • Select the highest-priority task with no blockers
  • Build a prompt from the task details
  • Execute your AI agent
  • Stream output in real-time
  • Detect completion and move to the next task

What Just Happened?

Let's break down what each step accomplished:

  1. Setup configured Ralph and installed the ralph-tui-prd skill for AI-powered PRD creation
  2. Create-prd had an AI conversation about your feature and created structured tasks
  3. Run started the autonomous loop - Ralph picks tasks, builds prompts, runs your agent, and marks tasks complete

Alternative: With Beads Tracker

If you use Beads for issue tracking, you can run Ralph with an epic:

Bash
# Run with a beads epic
ralph-tui run --epic my-project-epic

Beads provides additional features like:

  • Git-backed persistence
  • Task dependencies
  • Hierarchy (epics containing stories)
  • Labels and priorities

Alternative: Using Skills Directly in Your Agent

Prefer to stay in your agent's native interface? After running ralph-tui setup, you can use the installed skills directly:

Bash
# Use 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 approach lets you:

  • Reference files with @filename during PRD creation
  • Use your existing conversation context
  • Keep your preferred agent interface
INFO

Recommended hybrid workflow: Create your PRD using /ralph-tui-prd in your agent where you can reference source files, then use ralph-tui run for autonomous task execution.

Controlling Execution

While Ralph is running, use these keyboard shortcuts:

Execution Control

KeyAction
sStart execution
pPause/Resume execution
+ / =Add 10 iterations
- / _Remove 10 iterations
qQuit
?Show all shortcuts

Navigation

KeyAction
j / ↓Navigate down (task list, iteration history, or subagent tree)
k / ↑Navigate up
TabSwitch focus between panels (when subagent tree is visible)
EnterDrill into selected item
EscGo back / close dialog

View Controls

KeyAction
oCycle right panel views (details → output → prompt)
OJump directly to prompt preview
dToggle progress dashboard
hToggle show/hide closed tasks
rRefresh task list from tracker
TToggle subagent tree panel
tCycle subagent detail level (minimal → moderate → detailed)

File Browser

When selecting a PRD file (JSON tracker) or switching epics, a file browser appears with keyboard-driven navigation:

KeyAction
↑ / ↓Navigate entries
Enter / →Enter directory or select file
TabSelect highlighted entry
Backspace / ←Go to parent directory
~Jump to home directory
.Toggle hidden files
/ or gType a path directly
EscCancel / clear search

Fuzzy Search: Just start typing to filter files. Results are ranked by match quality — exact matches first, then partial matches. Use Tab or Enter to select the highlighted match. Press Esc to clear the search, or Backspace to delete characters.

Understanding the TUI

The terminal interface shows:

  • Left Panel: Task list with status indicators (✓ complete, ▶ active, ○ pending, ⊘ blocked)
  • Right Panel: Details view with three modes:
    • Details: Task metadata (title, description, dependencies)
    • Output: Live agent stdout/stderr
    • Prompt: Preview of the rendered prompt being sent to the agent
  • Subagent Tree Panel (toggle with T): Shows AI agent's spawned subagents in a tree hierarchy
    • Displays subagent type, description, status, and duration
    • Use Tab to switch focus, then j/k to navigate and see subagent details
    • Shows the task prompt given to each subagent and its result
  • Header: Current iteration count (e.g., [3/10]) and active task
  • Footer: Available keyboard shortcuts
INFO

Use O to preview the exact prompt being sent to your AI agent. Press T to see the subagent tree - this shows what autonomous subtasks the AI is spawning to complete your work.

Next Steps

Now that you have Ralph TUI running: