RalphTUI

https://ralph-tui.com/docs
Admin
RalphTUI is an AI agent loop orchestrator that automates autonomous coding by managing task...
Tokens:78,255
Snippets:1,177
Trust Score:3.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Basic Setup Example

Source: https://ralph-tui.com/docs/cli/setup

Navigate to your project directory and run the `ralph-tui setup` command to begin the interactive configuration process. The example shows typical prompts and successful completion messages.

```bash
cd your-project
ralph-tui setup
```

```text
Welcome to Ralph TUI Setup!

Detecting installed agents...
✓ Found: claude (Claude Code)
✓ Found: opencode (OpenCode)
✓ Found: droid (Factory Droid)

? Which agent should be the default?
❯ claude - Claude Code (recommended)
  opencode - OpenCode
  droid - Factory Droid

? Default tracker type?
❯ json - Simple JSON file (no dependencies)
  beads - Git-backed issue tracker
  beads-bv - Beads with graph analysis

? Maximum iterations per session? (0 = unlimited)
❯ 10

Creating configuration...
✓ Created .ralph-tui/config.toml

Installing skills...
✓ Installed ralph-tui-prd
✓ Installed ralph-tui-create-json
✓ Installed ralph-tui-create-beads

Setup complete! Next steps:
1. Create a PRD: ralph-tui create-prd --chat
2. Start Ralph: ralph-tui run --prd ./prd.json

```

--------------------------------

### Alias for Setup Command

Source: https://ralph-tui.com/docs/cli/setup

The `init` command serves as an alias for the `setup` command, providing an alternative way to start the interactive configuration wizard.

```bash
ralph-tui init    # Same as setup
```

--------------------------------

### Initialize Ralph TUI Project Setup

Source: https://ralph-tui.com/docs/getting-started/installation

Runs the Ralph TUI setup wizard in your project directory. This detects agents, creates configuration, and installs skills.

```bash
cd your-project
ralph-tui setup
```

--------------------------------

### Troubleshoot: No Agents Found

Source: https://ralph-tui.com/docs/cli/setup

If the setup wizard reports 'No agents found,' ensure you have at least one supported AI coding agent installed and accessible via your system's PATH. Use `which` to verify installation.

```bash
# Check for Claude Code
which claude

# Check for OpenCode
which opencode

# Check for Factory Droid
which droid

# If not found, install one:
# Claude Code: https://docs.anthropic.com/en/docs/claude-code
# OpenCode: https://github.com/opencode-ai/opencode
# Factory Droid: https://docs.factory.ai/reference/cli-reference
```

--------------------------------

### Install Beads CLI

Source: https://ralph-tui.com/docs/plugins/trackers/beads-bv

Installs the Beads CLI globally using bun. Ensure you have Node.js and bun installed.

```bash
bun install -g beads-cli
```

--------------------------------

### Install Kimi CLI on Linux/macOS

Source: https://ralph-tui.com/docs/plugins/agents/kimi

Use this command to install the Kimi CLI on Linux or macOS systems by downloading and executing an installation script.

```bash
# Linux / macOS
curl -LsSf https://code.kimi.com/install.sh | bash
```

--------------------------------

### Run Ralph TUI Setup Wizard

Source: https://ralph-tui.com/docs/configuration/overview

Use the setup command to interactively create a project configuration file.

```bash
ralph-tui setup

```

--------------------------------

### Run Ralph TUI with No Setup

Source: https://ralph-tui.com/docs/cli/run

Skip the interactive setup process, even if no configuration file exists.

```bash
ralph-tui run --no-setup
```

--------------------------------

### Install Kimi CLI Troubleshooting

Source: https://ralph-tui.com/docs/plugins/agents/kimi

If the Kimi CLI is not found, ensure it is installed and in your system's PATH. If not, use the provided curl command to install it.

```bash
kimi --version

# If not found, install:
curl -LsSf https://code.kimi.com/install.sh | bash
```

--------------------------------

### Run Interactive Setup Wizard

Source: https://ralph-tui.com/docs/cli/setup

Execute the `setup` command to launch the interactive wizard for configuring Ralph TUI. This is the recommended first step for new projects.

```bash
ralph-tui setup
```

--------------------------------

### Install bv CLI

Source: https://ralph-tui.com/docs/plugins/trackers/beads-rust-bv

Install the bv (beads-viewer) CLI using cargo or the project's install script. This tool is required for smart task selection.

```bash
cargo install bv
# or via the project's install script
curl -fsSL https://get.beads.sh/bv | sh
```

--------------------------------

### Example TOML Configuration

Source: https://ralph-tui.com/docs/configuration/overview

This is an example of a TOML configuration file used by Ralph TUI for global and project settings.

```toml
# Example configuration
agent = "claude"
tracker = "beads-bv"
maxIterations = 10
iterationDelay = 1000

```

--------------------------------

### Basic Resume Examples

Source: https://ralph-tui.com/docs/cli/resume

Demonstrates how to resume a session from the current directory or in headless mode for CI/CD pipelines.

```bash
# Resume from current directory
ralph-tui resume

```

```bash
# Resume headless for CI pipelines
ralph-tui resume --headless
```

--------------------------------

### Install Kimi CLI on Windows (PowerShell)

Source: https://ralph-tui.com/docs/plugins/agents/kimi

Execute this PowerShell command to install the Kimi CLI on Windows.

```powershell
# Windows (PowerShell)
Invoke-RestMethod https://code.kimi.com/install.ps1 | Invoke-Expression
```

--------------------------------

### Install Bun Runtime

Source: https://ralph-tui.com/docs/getting-started/installation

Installs the Bun runtime environment. Ensure Bun is installed to run Ralph TUI as it depends on Bun's native features.

```bash
curl -fsSL https://bun.sh/install | bash
```

--------------------------------

### Install Bubblewrap on Fedora

Source: https://ralph-tui.com/docs/configuration/sandbox

Use dnf to install Bubblewrap on Fedora.

```bash
sudo dnf install bubblewrap
```

--------------------------------

### Start Remote Listener

Source: https://ralph-tui.com/docs/cli/run

Enable remote monitoring and control by starting the Ralph TUI with the `--listen` flag. This starts a WebSocket server for remote connections.

```bash
ralph-tui run --prd ./prd.json --listen
```

```bash
ralph-tui run --epic my-feature --listen --listen-port 8080
```

```bash
ralph-tui run --prd ./prd.json --listen --rotate-token
```

--------------------------------

### Install WSL2

Source: https://ralph-tui.com/docs/configuration/sandbox

Install WSL2 on Windows if not already present.

```powershell
wsl --install
```

--------------------------------

### CLI Flag: Skip Setup Check

Source: https://ralph-tui.com/docs/configuration/options

Bypass the setup verification step. Overrides configuration settings.

```cli
--no-setup

```

--------------------------------

### Install Kimi CLI with uv

Source: https://ralph-tui.com/docs/plugins/agents/kimi

Install the Kimi CLI using the `uv` package manager for Python version 3.13.

```bash
uv tool install --python 3.13 kimi-cli
```

--------------------------------

### Install bv CLI

Source: https://ralph-tui.com/docs/plugins/trackers/beads-rust-bv

Install the bv CLI tool using cargo to enable smart selection features for the tracker.

```bash
cargo install bv
```

--------------------------------

### Install Claude CLI

Source: https://ralph-tui.com/docs/plugins/agents/claude

Ensure the Claude CLI is installed and accessible in your PATH. If not found, this command provides installation instructions.

```bash
which claude
# Should output: /path/to/claude

# If not found, install:
npm install -g @anthropic-ai/claude-code
```

--------------------------------

### Skip Setup and Run

Source: https://ralph-tui.com/docs/cli/setup

To run Ralph TUI without the interactive setup, use the `--no-setup` flag with the `run` command. Alternatively, manually create the `.ralph-tui/config.toml` file.

```bash
# Skip setup and use defaults
ralph-tui run --prd ./prd.json --no-setup

# Or create config manually
mkdir -p .ralph-tui
cat > .ralph-tui/config.toml << 'EOF'
tracker = "json"
agent = "claude"
maxIterations = 10
EOF
```

--------------------------------

### Example Workflow: Create PRD in Agent

Source: https://ralph-tui.com/docs/cli/setup

Demonstrates initiating PRD creation within an agent, including referencing existing code.

```chat
You: /ralph-tui-prd
Agent: I'll help you create a PRD. What feature would you like to plan?
You: I want to add user authentication. Here's our existing auth code: @src/auth/
Agent: [Asks clarifying questions, references your code]
```

--------------------------------

### Re-run Setup

Source: https://ralph-tui.com/docs/cli/setup

You can re-execute the `ralph-tui setup` command to update your project's configuration. The wizard will prompt before overwriting existing settings and will display your current configuration as defaults.

```bash
# Re-run setup (will ask before overwriting)
ralph-tui setup
```

--------------------------------

### Install Ralph TUI Globally with Bun

Source: https://ralph-tui.com/docs/getting-started/installation

Installs Ralph TUI globally using Bun. Bun is recommended for the fastest installation and best runtime compatibility.

```bash
# Install globally with Bun
bun install -g ralph-tui

# Verify installation
ralph-tui --version
```

--------------------------------

### Troubleshoot Permission Errors for Global Installation

Source: https://ralph-tui.com/docs/getting-started/installation

Ensures the global Bun installation directory exists and is writable to resolve permission errors during global package installation.

```bash
mkdir -p ~/.bun/install/global
```

--------------------------------

### Verify Pi Installation

Source: https://ralph-tui.com/docs/plugins/agents/pi

Check if the Pi CLI is installed correctly by running the version command. This should output the installed version number.

```bash
pi --version
# Should output version like: 0.55.0
```

--------------------------------

### Install Gemini CLI

Source: https://ralph-tui.com/docs/plugins/agents/gemini

Install the Gemini CLI globally using npm. This is a prerequisite for using the Gemini agent.

```bash
npm install -g @google/gemini-cli
```

--------------------------------

### Verify Gemini CLI Installation

Source: https://ralph-tui.com/docs/plugins/agents/gemini

Check if the Gemini CLI is installed correctly by verifying its version. This confirms the installation was successful.

```bash
gemini-cli --version
```

--------------------------------

### Install Bubblewrap on Debian/Ubuntu

Source: https://ralph-tui.com/docs/configuration/sandbox

Use apt to install Bubblewrap on Debian-based systems.

```bash
sudo apt install bubblewrap
```

--------------------------------

### Verify OpenCode CLI Installation

Source: https://ralph-tui.com/docs/plugins/agents/opencode

Check if the OpenCode CLI is installed and accessible in your system's PATH. If not found, instructions are provided to install it.

```bash
which opencode
# Should output: /path/to/opencode

# If not found, install:
curl -fsSL https://opencode.ai/install | bash
```

--------------------------------

### Install Bubblewrap on Arch Linux

Source: https://ralph-tui.com/docs/configuration/sandbox

Use pacman to install Bubblewrap on Arch Linux.

```bash
sudo pacman -S bubblewrap
```

--------------------------------

### Install OpenCode CLI

Source: https://ralph-tui.com/docs/plugins/agents/opencode

Install the OpenCode CLI using the provided curl command. This is a prerequisite for using the OpenCode agent.

```bash
curl -fsSL https://opencode.ai/install | bash
```

--------------------------------

### Verify OpenCode Installation

Source: https://ralph-tui.com/docs/plugins/agents/opencode

Verify that the OpenCode CLI has been installed successfully by checking its version.

```bash
opencode --version
```

--------------------------------

### Complete PRD JSON Example

Source: https://ralph-tui.com/docs/plugins/trackers/json

This is a comprehensive example of a `prd.json` file, including project details, user stories with acceptance criteria, and metadata.

```json
{
  "name": "User Authentication",
  "description": "Add user authentication to the application",
  "branchName": "feature/auth",
  "userStories": [
    {
      "id": "US-001",
      "title": "Create login page",
      "description": "As a user, I want to see a login form so I can access my account.",
      "acceptanceCriteria": [
        "Form has email and password inputs",
        "Form validates required fields",
        "Submit button is disabled during submission"
      ],
      "priority": 1,
      "passes": false,
      "dependsOn": []
    },
    {
      "id": "US-002",
      "title": "Implement authentication API",
      "description": "As a developer, I need an API endpoint to verify credentials.",
      "acceptanceCriteria": [
        "POST /api/auth/login accepts email and password",
        "Returns JWT token on success",
        "Returns 401 on invalid credentials"
      ],
      "priority": 1,
      "passes": false,
      "dependsOn": []
    },
    {
      "id": "US-003",
      "title": "Connect login form to API",
      "description": "Wire up the login form to call the authentication API.",
      "acceptanceCriteria": [
        "Form submits to /api/auth/login",
        "Success stores token and redirects",
        "Error shows message to user"
      ],
      "priority": 2,
      "passes": false,
      "dependsOn": ["US-001", "US-002"]
    }
  ],
  "metadata": {
    "createdAt": "2024-01-15T10:00:00Z",
    "version": "1.0"
  }
}
```

--------------------------------

### Install GitHub Copilot CLI

Source: https://ralph-tui.com/docs/plugins/agents/github-copilot

Install the GitHub Copilot CLI using package managers like Homebrew, npm, or winget. Ensure you have an active GitHub Copilot subscription.

```bash
# Install Copilot CLI
brew install copilot-cli
# Or: npm install -g @github/copilot
# Or: winget install GitHub.Copilot (Windows)
# Or: curl -fsSL https://gh.io/copilot-install | bash
```

--------------------------------

### Verify Copilot CLI Installation

Source: https://ralph-tui.com/docs/plugins/agents/github-copilot

Verify the installation of the GitHub Copilot CLI by checking its version.

```bash
copilot --version
```

--------------------------------

### Example Workflow: Convert PRD to Tasks

Source: https://ralph-tui.com/docs/cli/setup

Shows how to convert an existing PRD into prd.json format using an agent command.

```chat
You: /ralph-tui-create-json
Agent: I'll convert the PRD to prd.json format...
```

--------------------------------

### Install and Verify Factory Droid CLI

Source: https://ralph-tui.com/docs/plugins/agents/droid

Install the Factory Droid CLI and verify its installation by checking the version. Ensure it is accessible in your system's PATH.

```bash
# Install droid and ensure it is on your PATH
# (Follow Factory Droid installation instructions)

droid --version
```

--------------------------------

### Install Kiro CLI

Source: https://ralph-tui.com/docs/plugins/agents/kiro

Install the Kiro CLI using either curl or Homebrew. Visit the Kiro Downloads page for other platforms.

```bash
# Option 1: Install via curl
curl -fsSL https://cli.kiro.dev/install | bash

```

```bash
# Option 2: Install via Homebrew (macOS/Linux)
brew install kiro-cli

```

--------------------------------

### OpenCode File Context Example

Source: https://ralph-tui.com/docs/plugins/agents/opencode

Illustrates how OpenCode CLI can be used to attach files for context, with Ralph TUI automatically extracting file paths.

```bash
opencode run --file /path/to/context.ts
```

--------------------------------

### Install Pi CLI

Source: https://ralph-tui.com/docs/plugins/agents/pi

Install the Pi Coding Agent CLI globally using npm. Visit the Pi GitHub repository for instructions on other platforms.

```bash
npm install -g @mariozechner/pi-coding-agent
```

--------------------------------

### Verify Kimi CLI Installation

Source: https://ralph-tui.com/docs/plugins/agents/kimi

Check if the Kimi CLI is installed correctly by running this command to display its version.

```bash
kimi --version
```

--------------------------------

### Start Ralph with Remote Listener

Source: https://ralph-tui.com/docs/cli/overview

Use this command on the remote machine to start Ralph and enable the WebSocket server for remote control. Save the generated token shown on the first run for client configuration.

```bash
ralph-tui run --listen --prd ./prd.json
```

--------------------------------

### Headless/CI Setup Configuration

Source: https://ralph-tui.com/docs/configuration/config-file

Configure Ralph TUI for automated pipelines, disabling notifications and setting a fast-fail error handling strategy.

```toml
agent = "claude"
tracker = "json"
maxIterations = 50
autoCommit = true

[trackerOptions]
path = "./tasks/prd.json"

[errorHandling]
strategy = "abort"  # Fail fast in CI

[notifications]
enabled = false
```

--------------------------------

### OpenCode Model Variant Example

Source: https://ralph-tui.com/docs/plugins/agents/opencode

Example of running Ralph TUI with OpenCode, specifying a Google Gemini model and a 'max' variant for maximum reasoning effort.

```bash
ralph-tui run --agent opencode --model google/gemini-2.5-pro --variant max
```

--------------------------------

### Install Ollama for Local Models

Source: https://ralph-tui.com/docs/plugins/agents/opencode

Instructions for installing Ollama on macOS and Linux to enable local model execution. This is a prerequisite for using local models with Ralph TUI.

```bash
# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.ai/install.sh | sh
```

--------------------------------

### Quality Gate Integration Example

Source: https://ralph-tui.com/docs/cli/convert

Demonstrates how quality gates from a PRD are automatically appended to user story acceptance criteria in the JSON output.

```json
{
  "id": "US-001",
  "acceptanceCriteria": [
    "Form has email and password fields",
    "Submit button is disabled until valid",
    "bun run typecheck passes",
    "bun run lint passes"
  ]
}
```

--------------------------------

### Development Setup Configuration

Source: https://ralph-tui.com/docs/configuration/config-file

Use this TOML configuration for day-to-day development with the Claude agent and Beads-BV tracker.

```toml
agent = "claude"
tracker = "beads-bv"
maxIterations = 10
subagentTracingDetail = "moderate"

[errorHandling]
strategy = "skip"

[notifications]
enabled = true
```

--------------------------------

### Install Claude Code CLI

Source: https://ralph-tui.com/docs/plugins/agents/claude

Install the Claude Code CLI globally using npm. This is a prerequisite for using the agent.

```bash
npm install -g @anthropic-ai/claude-code
```

--------------------------------

### Configuration Merging: Project Overrides Global

Source: https://ralph-tui.com/docs/configuration/config-file

Example demonstrating how project configuration files override or merge with global configuration files.

```toml
# ~/.config/ralph-tui/config.toml (global)
agent = "claude"
maxIterations = 10

[agentOptions]
model = "claude-sonnet-4-20250514"
```

```toml
# .ralph-tui/config.toml (project)
maxIterations = 5  # Overrides global

[agentOptions]
timeout = 30000  # Merged with global agentOptions
```

--------------------------------

### Troubleshoot Kiro CLI Not Found

Source: https://ralph-tui.com/docs/plugins/agents/kiro

Verify that the Kiro CLI is installed and accessible in your system's PATH. If not found, follow the official installation guide.

```bash
which kiro-cli
# Should output: /path/to/kiro-cli

# If not found, follow installation at https://kiro.dev

```

--------------------------------

### Verify Bun Installation

Source: https://ralph-tui.com/docs/getting-started/installation

Checks if the Bun runtime is installed and outputs its version. Requires Bun version 1.0.0 or higher.

```bash
bun --version
```

--------------------------------

### Run Diagnostic Command

Source: https://ralph-tui.com/docs/troubleshooting/common-issues

Execute this command to check for common problems and get an overview of your Ralph TUI setup.

```bash
ralph-tui doctor
```

--------------------------------

### Task Dependency Example

Source: https://ralph-tui.com/docs/parallel/task-dependencies

Illustrates a set of tasks with their dependencies and how they form a dependency graph with different depth levels.

```text
A: "Set up database schema"         (no dependencies)
B: "Create API endpoints"           (depends on A)
C: "Write unit tests for API"       (depends on B)
D: "Design landing page"            (no dependencies)
E: "Build authentication flow"      (depends on A)
F: "Write integration tests"        (depends on B, E)

```

```text
Depth 0:  A ─────────── D
          │
Depth 1:  B ──── E
          │     │
Depth 2:  C     F

```

--------------------------------

### Initialize Beads in Project

Source: https://ralph-tui.com/docs/plugins/trackers/beads-bv

Navigates to your project directory and initializes Beads.

```bash
cd your-project
bd init
```

--------------------------------

### Verify Tool Versions

Source: https://ralph-tui.com/docs/plugins/trackers/beads-rust-bv

Verify that both the br and bv CLIs are installed and accessible on your system's PATH.

```bash
br --version   # e.g. br 1.0.0
bv --version   # e.g. bv 0.5.0
```

--------------------------------

### Get Ralph TUI Version

Source: https://ralph-tui.com/docs/troubleshooting/debugging

Retrieve the installed Ralph TUI version using the command `ralph-tui --version`.

```bash
ralph-tui --version
```

--------------------------------

### Gemini Model Validation Examples

Source: https://ralph-tui.com/docs/plugins/agents/gemini

Demonstrates valid and invalid model names for the Gemini agent. Model names must start with 'gemini-' to be recognized.

```typescript
// Valid models
"gemini-2.5-pro"
"gemini-2.5-flash"

// Invalid - will show error
"gpt-4"
"claude-3"
```

--------------------------------

### Generated Configuration File

Source: https://ralph-tui.com/docs/cli/setup

The `setup` command creates a `.ralph-tui/config.toml` file. This TOML file stores your selected default agent, tracker, execution limits, and agent-specific options.

```toml
# .ralph-tui/config.toml (created by setup) 

# Default tracker and agent
tracker = "json"
agent = "claude"

# Execution limits
maxIterations = 10

# Agent-specific options
[agentOptions]
model = "sonnet"

# Error handling
[errorHandling]
strategy = "skip"
maxRetries = 3
retryDelayMs = 5000
```

--------------------------------

### Display System Information

Source: https://ralph-tui.com/docs/cli/info

Run this command to display general system information for your RalphTUI installation. This is useful for basic checks.

```bash
# Display system info
ralph-tui info
```

--------------------------------

### User Story Best Practices: Order Dependencies

Source: https://ralph-tui.com/docs/cli/create-prd

Demonstrates how to order user stories based on their dependencies.

```markdown
### US-001: Create database schema (no dependencies)
### US-002: Implement backend API (depends on US-001)
### US-003: Build frontend components (depends on US-002)

```

--------------------------------

### OpenCode Agent Model Options

Source: https://ralph-tui.com/docs/cli/run

Example of how to specify OpenCode agent models using the provider/model format, such as for Anthropic, OpenAI, Google, XAI, or Ollama.

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

--------------------------------

### Configure Full Tracker

Source: https://ralph-tui.com/docs/configuration/options

Defines a full tracker configuration with a name, plugin, and specific options. Use this for more detailed tracker setups.

```toml
[[trackers]]
name = "my-tracker"
plugin = "beads-bv"
default = true
 
  [trackers.options]
  epicId = "beads-001"
```

--------------------------------

### High-Reliability Setup Configuration

Source: https://ralph-tui.com/docs/configuration/config-file

This configuration enables maximum retry capability for critical tasks, including fallback agents and detailed rate limit handling.

```toml
agent = "claude"
fallbackAgents = ["opencode"]

[errorHandling]
strategy = "retry"
maxRetries = 5
retryDelayMs = 10000

[rateLimitHandling]
enabled = true
maxRetries = 5
baseBackoffMs = 10000
```

--------------------------------

### Install Codex CLI

Source: https://ralph-tui.com/docs/plugins/agents/codex

Install the OpenAI Codex CLI globally using npm. Ensure Node.js and npm are installed.

```bash
npm install -g @openai/codex
```

--------------------------------

### Custom Template Path Example

Source: https://ralph-tui.com/docs/templates/overview

Use a custom Handlebars template by specifying its path with the --prompt argument.

```bash
ralph-tui run --prompt ./my-template.hbs
```

--------------------------------

### Claude Agent Model Options

Source: https://ralph-tui.com/docs/cli/run

Example of how to specify Claude agent models like Sonnet, Opus, or Haiku.

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

--------------------------------

### Verify Cursor CLI Path

Source: https://ralph-tui.com/docs/plugins/agents/cursor

Troubleshoot 'Cursor CLI not found' errors by verifying the installation path of the `agent` executable.

```bash
which agent
# Should output: /path/to/agent
```

--------------------------------

### Verify Kiro CLI Installation

Source: https://ralph-tui.com/docs/plugins/agents/kiro

Check if the Kiro CLI is installed correctly by running the version command. It should output the installed version number.

```bash
kiro-cli -V
# Should output version like: kiro-cli 1.0.0

```

--------------------------------

### OpenCode Provider Models

Source: https://ralph-tui.com/docs/plugins/agents/opencode

Examples of specifying models for different AI providers supported by OpenCode, including Anthropic, OpenAI, Google, xAI, and Ollama.

```bash
--model anthropic/claude-3-5-sonnet
--model anthropic/claude-3-opus
```

```bash
--model openai/gpt-4o
--model openai/gpt-4-turbo
```

```bash
--model google/gemini-pro
--model google/gemini-1.5-pro
```

```bash
--model xai/grok-1
```

```bash
--model ollama/llama3
--model ollama/codellama
```

--------------------------------

### Sample Copyable System Information Output

Source: https://ralph-tui.com/docs/cli/info

An example of the compact, copyable output generated by `ralph-tui info -c`, designed for easy inclusion in bug reports.

```text
ralph-tui: 0.2.1
runtime: bun 1.2.5
os: linux 6.18.3 (x64)
agent: claude v1.0.28
tracker: beads
global-config: yes
project-config: yes
templates: default.hbs, custom.hbs


```

--------------------------------

### Sample Default System Information Output

Source: https://ralph-tui.com/docs/cli/info

This is an example of the default output from the `ralph-tui info` command, showing version, runtime, OS, configuration, templates, agent, and tracker details.

```text
ralph-tui System Information
============================

ralph-tui version: 0.2.1
Runtime: bun 1.2.5
OS: linux 6.18.3 (x64)

Configuration:
  Global config: /home/user/.config/ralph-tui/config.toml
    Exists: yes
  Project config: /home/user/project/.ralph-tui/config.toml
    Exists: yes

Templates:
  Directory: /home/user/.config/ralph-tui/templates
  Installed: default.hbs, custom.hbs

Agent:
  Configured: claude
  Available: yes
  Version: 1.0.28

Tracker:
  Configured: beads

Tip: Use ralph-tui info -c for a copyable bug report format

```

--------------------------------

### Select Claude Model via CLI Example

Source: https://ralph-tui.com/docs/plugins/agents/claude

Demonstrates selecting the 'opus' model directly from the command line when running a Ralph TUI task.

```bash
# CLI
ralph-tui run --prd ./prd.json --model opus
```

--------------------------------

### Reset Session and Run

Source: https://ralph-tui.com/docs/troubleshooting/common-issues

Remove the existing session file and start a new run. Use this if other troubleshooting steps fail to resolve session issues.

```bash
rm .ralph-tui/session.json
ralph-tui run --prd ./prd.json
```

--------------------------------

### Initialize a Custom Template

Source: https://ralph-tui.com/docs/templates/customization

Use this command to create a `.ralph-tui-prompt.hbs` file in your project root, pre-populated with the current template.

```bash
ralph-tui template init
```

```bash
# or equivalently:
ralph-tui template install
```

--------------------------------

### Start Ralph-TUI Server for Remote Orchestration

Source: https://ralph-tui.com/docs/cli/remote

Initiates a Ralph-TUI server with parallel processing capabilities and enables remote client connections via WebSocket.

```bash
ralph-tui run --prd ./prd.json --listen
```

--------------------------------

### Install ralph-tui inside WSL

Source: https://ralph-tui.com/docs/configuration/sandbox

Install ralph-tui within your WSL distribution.

```bash
# Inside your WSL distribution
curl -fsSL https://get.ralph-tui.dev | bash
```

--------------------------------

### Complete Ralph TUI Configuration Example

Source: https://ralph-tui.com/docs/configuration/config-file

An annotated configuration file demonstrating all available options for Ralph TUI. This includes core settings, agent and tracker options, error handling, rate limiting, notifications, and parallel execution.

```toml
# .ralph-tui/config.toml
# ─────────────────────────────────────────────
# Core Settings
# ─────────────────────────────────────────────

# Default agent plugin name
agent = "claude"

# Default model for the selected agent (optional)
model = "sonnet"

# Custom command (optional) - use wrapper tools like Claude Code Router
# command = "ccr code"

# Default tracker plugin name
tracker = "beads-bv"

# Maximum iterations per session (0 = unlimited)
maxIterations = 10

# Delay between iterations in milliseconds
iterationDelay = 1000

# Output directory for iteration logs
outputDir = ".ralph-tui/iterations"

# Progress file for cross-iteration context
progressFile = ".ralph-tui/progress.md"

# Auto-commit: when true, ralph-tui stages and commits all changes after each
# successful task completion. When false, no automatic commit is made (agents
# may still commit on their own if instructed by templates or CLAUDE.md).
autoCommit = false

# Optional Handlebars template for the auto-commit subject line. Variables:
#   {{taskId}}    - tracker-supplied task identifier
#   {{taskTitle}} - tracker-supplied task title
#   {{taskType}}  - task type (e.g. "bug", "feature"); falls back to "chore"
# If unset, the default below is used. To restore the legacy `feat:` prefix used
# in pre-#384 releases, set:
#   commitMessageTemplate = "feat: {{taskId}} - {{taskTitle}}"
# commitMessageTemplate = "{{taskType}}: {{taskId}} {{taskTitle}}"

# Custom prompt template path (relative or absolute)
# prompt_template = "./my-template.hbs"

# Subagent tracing detail: "off", "minimal", "moderate", "full"
subagentTracingDetail = "minimal"

# Preflight check timeout in ms (1000-300000, default 30000).
# Increase for local reasoning models that need longer to respond.
# preflightTimeoutMs = 60000

# ─────────────────────────────────────────────
# Agent Options (shorthand)
# ─────────────────────────────────────────────

[agentOptions]
# These options are passed to the selected agent plugin.
# Prefer top-level `model` for the default runtime model.

# ─────────────────────────────────────────────
# Tracker Options (shorthand)
# ─────────────────────────────────────────────

[trackerOptions]
# These options are passed to the selected tracker plugin
# Example for beads-bv tracker:
# epicId = "beads-001"
# For multi-epic runs, prefer runtime flags:
# ralph-tui run --parallel --epic ui-epic --epic backend-epic

# ─────────────────────────────────────────────
# Error Handling
# ─────────────────────────────────────────────

[errorHandling]
# Strategy when a task fails: "retry", "skip", or "abort"
strategy = "skip"

# Maximum retry attempts (when strategy = "retry")
maxRetries = 3

# Delay between retries in milliseconds
retryDelayMs = 5000

# Continue even if agent exits with non-zero code
continueOnNonZeroExit = false

# ─────────────────────────────────────────────
# Rate Limit Handling
# ─────────────────────────────────────────────

# Fallback agents when primary hits rate limits
fallbackAgents = ["opencode"]

[rateLimitHandling]
# Enable automatic fallback to secondary agents
enabled = true

# Retries before switching to fallback
maxRetries = 3

# Base backoff time for exponential retry (ms)
baseBackoffMs = 5000

# Try primary agent again between iterations
recoverPrimaryBetweenIterations = true

# ─────────────────────────────────────────────
# Notifications
# ─────────────────────────────────────────────

[notifications]
# Enable desktop notifications
enabled = true

# Sound mode: "off", "system", or "ralph"
sound = "off"

# ─────────────────────────────────────────────
# Parallel Execution
# ─────────────────────────────────────────────

[parallel]
# Mode: "auto" (analyze dependencies), "always" (force parallel), "never" (disable)
mode = "never"

# Maximum concurrent workers (git worktrees)
maxWorkers = 3

# Directory for worker worktrees (relative to project root)
worktreeDir = ".ralph-tui/worktrees"

```

--------------------------------

### Troubleshooting: Create Output Directory

Source: https://ralph-tui.com/docs/cli/create-prd

Commands to create the necessary output directory and initiate the PRD creation process.

```bash
mkdir -p ./tasks
ralph-tui create-prd --chat

```

--------------------------------

### Common Quality Gates Example

Source: https://ralph-tui.com/docs/cli/create-prd

An example of quality gates that are typically included in a PRD.

```markdown
## Quality Gates

These commands must pass for every user story:
- `bun run typecheck` - Type checking
- `bun run lint` - Linting
- `bun run build` - Build verification
- `bun run test` - Unit tests

```

--------------------------------

### Correct Provider/Model Format

Source: https://ralph-tui.com/docs/plugins/agents/opencode

Illustrates the correct format for specifying the provider and model when configuring agents. Ensure the format is 'provider/model' for clarity and proper parsing.

```bash
# Wrong
--model claude-3-5-sonnet

# Correct
--model anthropic/claude-3-5-sonnet
```

--------------------------------

### Verify Codex Installation

Source: https://ralph-tui.com/docs/plugins/agents/codex

Check if the Codex CLI is installed correctly and accessible in your system's PATH.

```bash
codex --version
```

--------------------------------

### Verify Cursor CLI Installation

Source: https://ralph-tui.com/docs/plugins/agents/cursor

Check if the Cursor CLI is installed and accessible in your system's PATH.

```bash
agent --version
```

--------------------------------

### Verify Claude Code CLI Installation

Source: https://ralph-tui.com/docs/plugins/agents/claude

Verify that the Claude Code CLI has been installed correctly by checking its version.

```bash
claude --version
```

--------------------------------

### Troubleshoot: Skills Permission Denied

Source: https://ralph-tui.com/docs/cli/setup

If you encounter 'Permission denied' errors related to skills installation, verify that the relevant agent's skills directory is writable. Use `ralph-tui skills list` to identify the directory and create it if necessary.

```bash
# Check which directory skills are installed to
ralph-tui skills list

# Create skills directory if needed (per agent)
mkdir -p ~/.claude/skills           # Claude Code
mkdir -p ~/.config/opencode/skills  # OpenCode
mkdir -p ~/.factory/skills          # Factory Droid
```

--------------------------------

### Initialize Beads-Rust Tracker

Source: https://ralph-tui.com/docs/plugins/trackers/beads-rust

Initialize the Beads-Rust tracker in your project. This creates a .beads/ directory containing the SQLite database and JSONL export.

```bash
cd your-project
br init
```

--------------------------------

### Initialize Beads-Rust Tracker

Source: https://ralph-tui.com/docs/plugins/trackers/beads-rust

Run this command to initialize the Beads-Rust tracker in your project if the Beads directory is not found.

```bash
br init
```

--------------------------------

### Create Tasks with Beads CLI (Concepts)

Source: https://ralph-tui.com/docs/plugins/trackers/beads

Illustrates creating individual tasks, both standalone and as children of an epic, using the Beads CLI.

```bash
# Create standalone task
bd create --title "Fix login bug" --type task

# Create task under epic
bd create --title "Add toggle switch" --type task --parent beads-xyz
```

--------------------------------

### Kimi CLI Login Troubleshooting

Source: https://ralph-tui.com/docs/plugins/agents/kimi

Authenticate the Kimi CLI on first run by executing `kimi` and entering `/login`, or by using the `kimi login` subcommand.

```bash
kimi
# Then type: /login

# Or use the subcommand:
kimi login
```

--------------------------------

### Copy Existing Theme as Starting Point

Source: https://ralph-tui.com/docs/configuration/themes

To create a new custom theme, copy an existing theme file (e.g., 'dracula.json') to a new name (e.g., 'my-theme.json') and then edit the colors.

```bash
cp assets/themes/dracula.json my-theme.json

```

--------------------------------

### Configure Shorthand Tracker

Source: https://ralph-tui.com/docs/configuration/options

Sets up a tracker using shorthand configuration, specifying the tracker plugin and its options.

```toml
tracker = "beads-bv"

[trackerOptions]
epicId = "beads-001"
```

--------------------------------

### Audit Logging Example

Source: https://ralph-tui.com/docs/cli/run

Example of audit log entries showing remote actions and their success status. These logs are stored in `~/.config/ralph-tui/audit.log`.

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

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

--------------------------------

### Create an Epic with Beads CLI (Concepts)

Source: https://ralph-tui.com/docs/plugins/trackers/beads

Demonstrates creating a top-level epic using the Beads CLI. Epics are used to group related work items.

```bash
# Create an epic
bd create --title "Feature: Dark Mode" --type epic

# List epics
bd list --type epic
```

--------------------------------

### Verify Agent Installation

Source: https://ralph-tui.com/docs/troubleshooting/common-issues

Check if your AI agent CLI executable (e.g., Claude Code, OpenCode) is installed and accessible in your system's PATH.

```bash
which claude      # For Claude Code
```

```bash
which opencode    # For OpenCode
```

--------------------------------

### Full Theme File Structure Example

Source: https://ralph-tui.com/docs/configuration/themes

A complete theme file defines colors for background, foreground, status, tasks, accents, and borders. Missing values will fall back to the default theme.

```json
{
  "bg": {
    "primary": "#0a0a0f",
    "secondary": "#12121a",
    "tertiary": "#1a1a24",
    "highlight": "#22222e"
  },
  "fg": {
    "primary": "#ffffff",
    "secondary": "#f0f0f0",
    "muted": "#b0b0c0",
    "dim": "#808090"
  },
  "status": {
    "success": "#00ff66",
    "warning": "#ffdd00",
    "error": "#ff4477",
    "info": "#44ddff"
  },
  "task": {
    "done": "#00ff66",
    "active": "#00ff66",
    "actionable": "#66ff00",
    "pending": "#9090a0",
    "blocked": "#ff4477",
    "error": "#ff2255",
    "closed": "#606070"
  },
  "accent": {
    "primary": "#44ddff",
    "secondary": "#ff44dd",
    "tertiary": "#ffff44"
  },
  "border": {
    "normal": "#3a3a4a",
    "active": "#44ddff",
    "muted": "#2a2a3a"
  }
}

```

--------------------------------

### Verify Ralph TUI Installation and Configuration

Source: https://ralph-tui.com/docs/getting-started/installation

Commands to verify the Ralph TUI installation, list detected agents and trackers, and view the current configuration.

```bash
# Check Ralph TUI version
ralph-tui --version

# List detected agents
ralph-tui plugins agents

# List detected trackers
ralph-tui plugins trackers

# View current configuration
ralph-tui config show
```

--------------------------------

### Configure Beads-BV Tracker in config.toml

Source: https://ralph-tui.com/docs/plugins/trackers/beads-bv

Sets the Beads-BV tracker as the default and specifies options like the .beads directory and optional label filtering in the .ralph-tui/config.toml file.

```toml
# .ralph-tui/config.toml
tracker = "beads-bv"

[trackerOptions]
beadsDir = ".beads"
# labels = "frontend,backend"  # Optional: filter by labels
```

--------------------------------

### OpenCode CLI Arguments Construction

Source: https://ralph-tui.com/docs/plugins/agents/opencode

Demonstrates how Ralph TUI constructs the `opencode run` command with various arguments, including model, agent type, format, file context, and prompt via stdin.

```bash
opencode run \
  --model anthropic/claude-3-5-sonnet \
  # If model specified
  --agent general \
  # If not default
  --format default \
  # If not default
  --file /path/to/context.ts \
  # From file context
  < prompt.txt \
  # Prompt via stdin

```

--------------------------------

### Multi-Epic Remote Orchestration Start (TypeScript)

Source: https://ralph-tui.com/docs/cli/remote

Starts a parallel orchestration session that spans multiple epics. The server manages a single worker pool and merge queue for all specified epics.

```typescript
const result = await client.startOrchestration({
  epicIds: ['ui-epic', 'backend-epic'],
  maxWorkers: 4,
  directMerge: false,
});
```

--------------------------------

### Force Start Ralph with Lock Conflict Resolution

Source: https://ralph-tui.com/docs/parallel/troubleshooting

If a previous Ralph session did not clean up its lock file, you can use the `--force` flag to start a new session, which will remove the stale lock. Alternatively, you can manually remove the lock file.

```bash
# Force start (removes stale lock)
ralph-tui run --force
 
# Or manually remove the lock
rm .ralph-tui/session.lock
```

--------------------------------

### Troubleshooting: Test Agent CLI

Source: https://ralph-tui.com/docs/cli/create-prd

Commands to test if the Claude Code and OpenCode CLIs are installed and responding.

```bash
# Test Claude Code
claude --version

# Test OpenCode
opencode --version

```

--------------------------------

### Minimal PRD JSON Structure

Source: https://ralph-tui.com/docs/plugins/trackers/json

A basic `prd.json` structure to start with, containing only the essential fields for a task.

```json
{
  "name": "My Task",
  "userStories": [
    {
      "id": "US-001",
      "title": "First task",
      "passes": false
    }
  ]
}
```

--------------------------------

### User Story Best Practices: Keep Stories Small

Source: https://ralph-tui.com/docs/cli/create-prd

Illustrates how to split large features into smaller, manageable user stories.

```markdown
# Too big - split this
### US-001: Implement user authentication system

# Better - separate concerns
### US-001: Add login form component
### US-002: Create authentication API endpoints
### US-003: Implement session management
### US-004: Add logout functionality

```

--------------------------------

### Run Ralph TUI with Beads-Rust-BV Tracker

Source: https://ralph-tui.com/docs/plugins/trackers/beads-rust-bv

Run Ralph TUI using the beads-rust-bv tracker. Ralph will use bv --robot-next to select tasks based on graph analysis.

```bash
ralph run --tracker beads-rust-bv
```

--------------------------------

### Create PRD and Convert to Beads Issues

Source: https://ralph-tui.com/docs/plugins/trackers/beads

Create a Product Requirements Document (PRD) using 'ralph-tui create-prd --chat' and choose 'Beads' format when prompted, or manually convert an existing Markdown file to Beads format.

```bash
# Create PRD
ralph-tui create-prd --chat

# When prompted, choose "Beads" format
# Or convert manually:
ralph-tui convert --to beads ./tasks/my-prd.md
```

--------------------------------

### Configuration Validation Errors

Source: https://ralph-tui.com/docs/configuration/config-file

Example of validation errors that Ralph TUI might display for an invalid configuration file.

```text
Configuration error in .ralph-tui/config.toml:
  • maxIterations: Number must be less than or equal to 1000
  • errorHandling.strategy: Invalid enum value. Expected 'retry' | 'skip' | 'abort'


```

--------------------------------

### Example Task Lists

Source: https://ralph-tui.com/docs/parallel/configuration

Heuristics adjust parallelism based on task content. Test-related tasks allow for full parallelism, while refactoring tasks reduce it to minimize conflicts.

```text
1. Write unit tests for UserService
2. Add tests for AuthController
3. Test coverage for OrderProcessor
4. Add integration tests for PaymentService
```

```text
1. Refactor database layer
2. Refactor API endpoints
3. Refactor auth middleware
```

--------------------------------

### Create and List Epics with Beads-Rust

Source: https://ralph-tui.com/docs/plugins/trackers/beads-rust

Demonstrates creating a new epic and listing all existing epics using the Beads-Rust CLI.

```bash
# Create an epic
br create --title "Feature: Dark Mode" --type epic
 
# List epics
br list --type epic
```
Tokens:
Raw