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:

Switching Agent or Model During a Run

Press a in the local TUI to open the Agent & Model picker. Choose an agent in the left column and a model in the right column. Agents with known model lists show selectable models; agents that accept open-ended model names use a free-text model field.

Use Tab to switch columns, Enter to apply, and Esc to cancel. The selected agent and model are used on the next iteration.

Enable Save as default to write the selection to .ralph-tui/config.toml. Leave it unchecked for a session-only switch.

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

Multi-Epic Parallel Runs

Hierarchy trackers such as Beads, Beads-Rust, and Beads-BV can run one parallel session across multiple selected epics:

# Repeat --epic
ralph-tui run --parallel --epic ui-epic --epic backend-epic
 
# Or use comma-separated IDs
ralph-tui run --parallel --epics ui-epic,backend-epic

Multi-epic mode is one orchestration session, not several local runners. Ralph uses one scheduler, one repo lock, one session branch, and one sequential merge queue. Each task still gets its own worker branch and worktree.

If you launch a hierarchy tracker without --epic and the TUI is enabled, the epic picker supports multi-select:

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)
• Selected epic IDs and execution scopes for multi-epic runs

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>
 
# Add a TLS-terminated remote behind a reverse proxy
ralph-tui remote add prod ralph.example.com:443 --secure --token <token>
 
# View remote in TUI
ralph-tui run
# Then press number keys to switch between local and remote tabs

Use --secure for remotes exposed through TLS-terminating proxies such as Caddy or nginx. Secure remotes connect with wss://; port 443 is omitted from displayed URLs.

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}

Remote-Only Mode

Pass --remote-only to start the TUI as a pure remote client: no local execution engine, no local session/lock, no local tab. The TUI loads your configured remotes and lets you switch between them. Useful when you want to drive multiple remote machines (e.g., several GPU boxes) from one TUI on a workstation that isn't itself running a Ralph engine.

Requirements

• At least one remote configured in ~/.config/ralph-tui/remotes.toml (add one with ralph-tui remote add).
• The TUI must be visible — --remote-only cannot be combined with --headless / --no-tui.

Behavior

Examples

# Connect to all configured remotes as a pure client
ralph-tui run --remote-only
 
# Pair with a theme override (display options still apply)
ralph-tui run --remote-only --theme dracula

Flag conflicts

These combinations exit with a clear error:

ralph-tui run --remote-only --headless    # cannot run without TUI
ralph-tui run --remote-only --no-tui      # same as --headless
ralph-tui run --remote-only --listen      # --listen requires a local engine to expose

Fail-fast when no remotes are configured

If ~/.config/ralph-tui/remotes.toml is empty (or missing), --remote-only exits with exit code 1 and prints:

Error: --remote-only requires at least one configured remote.

No remotes found in ~/.config/ralph-tui/remotes.toml.

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

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