run

Synopsis

ralph-tui run [options]

The run command starts the autonomous execution loop. Ralph will select tasks, build prompts, execute your AI agent, detect completion, and repeat until all tasks are done or the iteration limit is reached.

Options

Task Source Options

Agent & Model Options

Execution Control

Output & State

Display Options

Model Options

The --model flag accepts different values depending on which agent you're using.

Claude Agent

ralph-tui run --agent claude --model <model>

OpenCode Agent

ralph-tui run --agent opencode --model <provider>/<model>

Models use provider/model format. Valid providers:

Examples

Basic Usage with JSON Tracker

# Run with a prd.json file
ralph-tui run --prd ./prd.json
 
# Limit to 5 iterations
ralph-tui run --prd ./prd.json --iterations 5

Using Beads Tracker

# Run with a beads epic
ralph-tui run --epic my-feature-epic
 
# Use beads-bv for intelligent task selection
ralph-tui run --epic my-feature-epic --tracker beads-bv

Agent & Model Override

# Use Claude Opus for complex tasks
ralph-tui run --prd ./prd.json --agent claude --model opus
 
# Use OpenCode with GPT-4
ralph-tui run --prd ./prd.json --agent opencode --model openai/gpt-4o

Custom Prompt Template

# Use a custom Handlebars template
ralph-tui run --prd ./prd.json --prompt ./my-template.hbs

Headless Mode (CI/Scripts)

# Run without TUI for automation
ralph-tui run --prd ./prd.json --headless --iterations 10

Development Workflow

# Add delay between iterations for monitoring
ralph-tui run --prd ./prd.json --delay 5000
 
# Custom output directory for logs
ralph-tui run --prd ./prd.json --output-dir ./logs/ralph

Execution Flow

When you run this command, Ralph:

1. Loads configuration from .ralph-tui/config.toml
2. Connects to tracker (json, beads, or beads-bv)
3. Selects next task based on priority and dependencies
4. Builds prompt using the Handlebars template
5. Spawns agent with the prompt
6. Streams output to the TUI (or stdout in headless mode)
7. Detects completion via <promise>COMPLETE</promise> token
8. Marks task done and proceeds to next task
9. Repeats until no tasks remain or max iterations reached

Session Persistence

Ralph automatically saves state to .ralph-tui/session.json:

• Current iteration number
• Task statuses
• Iteration history
• Active task IDs (for crash recovery)

If interrupted, use ralph-tui resume to continue.

Remote Listener

Enable remote monitoring and control by adding the --listen flag. This starts a WebSocket server alongside the execution engine, allowing you to connect from another machine.

Remote Options

First Run: Token Generation

On first use of --listen, a secure authentication token is generated:

═══════════════════════════════════════════════════════════════
                   Server Authentication Token
═══════════════════════════════════════════════════════════════

  A new server token has been generated:

  OGQwNTcxMjM0NTY3ODkwYWJjZGVmMDEyMzQ1Njc4OQ

  ⚠️  IMPORTANT: This token is shown only once. Save it securely.
     You will need it to connect remote clients to this instance.

═══════════════════════════════════════════════════════════════

Save this token securely! You'll need it to configure remote clients.

Examples

# Start with remote listener on default port (7890)
ralph-tui run --prd ./prd.json --listen
 
# Use custom port
ralph-tui run --epic my-feature --listen --listen-port 8080
 
# Rotate token and start (invalidates old connections)
ralph-tui run --prd ./prd.json --listen --rotate-token

Connecting from Remote

After starting with --listen, connect from another machine:

# Add remote connection
ralph-tui remote add prod server.example.com:7890 --token <token>
 
# View remote in TUI
ralph-tui run
# Then press number keys to switch between local and remote tabs

Security Model

Ralph uses a two-tier token system:

Host binding:

• Without --listen: binds to 127.0.0.1 (local only)
• With --listen: binds to 0.0.0.0 (network accessible, requires token auth)

Audit Logging

All remote actions are logged to ~/.config/ralph-tui/audit.log:

{"timestamp":"2026-01-19T15:30:00.000Z","clientId":"abc12345@192.168.1.100","action":"connection_connect","success":true}
{"timestamp":"2026-01-19T15:30:05.000Z","clientId":"abc12345@192.168.1.100","action":"pause","success":true}

Parallel Execution

By default, ralph-tui runs sequentially. Parallel execution is opt-in via --parallel or configuration (parallel.mode = "auto" or parallel.mode = "always"). Each parallel worker runs in its own git worktree for full isolation.

# Default behavior (sequential)
ralph-tui run --prd ./prd.json
 
# Force parallel with 4 workers
ralph-tui run --prd ./prd.json --parallel 4
 
# Force sequential (disable parallel)
ralph-tui run --prd ./prd.json --serial

To enable automatic parallel detection on normal run invocations, set parallel.mode = "auto" in your config.

When parallel mode is active, the TUI shows additional views:

• Press w to toggle the workers view
• Press m to toggle the merge progress view
• Press Enter on a worker to see its detail output

See the Parallel Execution guide for full documentation.

Task Range Filtering

The --task-range flag lets you filter tasks by their position in the task list. Task indices are 1-indexed for user friendliness.

Range Formats

Examples

# Run only the first 5 tasks
ralph-tui run --prd ./prd.json --task-range 1-5
 
# Skip the first 2 tasks, run the rest
ralph-tui run --prd ./prd.json --task-range 3-
 
# Run tasks 1-10 only (useful for large PRDs)
ralph-tui run --prd ./prd.json --task-range -10
 
# Run just task 3
ralph-tui run --prd ./prd.json --task-range 3
 
# Combine with parallel for targeted parallel execution
ralph-tui run --prd ./prd.json --task-range 5-15 --parallel 4

Related Commands

• resume - Continue an interrupted session
• status - Check session status
• logs - View iteration output logs
• remote - Manage remote server connections