Debugging | Ralph TUI

Overview

When something goes wrong with Ralph TUI, systematic debugging helps identify the root cause quickly. This guide covers the diagnostic tools and techniques available.

INFO

Start with the simplest diagnostic (logs) before moving to more complex debugging. Most issues can be resolved by examining iteration output.

Iteration Logs

Ralph TUI automatically saves output from each iteration to the .ralph-tui/iterations/ directory.

Viewing Logs

Bash

# View the most recent iteration
ralph-tui logs
 
# View a specific iteration
ralph-tui logs --iteration 5
 
# View logs for a specific task
ralph-tui logs --task US-005
 
# View full output without truncation
ralph-tui logs --iteration 5 --verbose

Log File Location

.ralph-tui/
└── iterations/
    ├── iteration-001.json
    ├── iteration-002.json
    └── ...

Each log file contains:

Task ID and details
Full agent stdout/stderr
Timestamps and duration
Exit codes and completion status

Searching Logs

Bash

# Search for errors across all iterations
grep -r "error" .ralph-tui/iterations/
 
# Find completion tokens
grep -r "COMPLETE" .ralph-tui/iterations/
 
# Search for specific task mentions
grep -r "US-005" .ralph-tui/iterations/

Cleaning Up Logs

Old logs can accumulate and consume disk space:

Bash

# Preview what would be deleted
ralph-tui logs --clean --keep 10 --dry-run
 
# Delete old logs, keeping the 10 most recent
ralph-tui logs --clean --keep 10

Session Inspection

The session file (.ralph-tui/session.json) contains the complete state of your Ralph TUI session.

Session metadata is stored separately in .ralph-tui/session-meta.json. Lock information is stored in .ralph-tui/ralph.lock.

Viewing Session State

Bash

# Quick status check
ralph-tui status
 
# JSON output for scripting
ralph-tui status --json
 
# Raw session file (when ralph-tui isn't running)
cat .ralph-tui/session.json | jq .

Session File Structure

JSON

{
  "version": 1,
  "sessionId": "ses_abc123",
  "status": "running",
  "startedAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:45:00Z",
  "currentIteration": 5,
  "maxIterations": 10,
  "tasksCompleted": 2,
  "isPaused": false,
  "agentPlugin": "droid",
  "model": "claude-opus-4-5-20251101",
  "trackerState": {
    "plugin": "beads-bv",
    "epicId": "ralph-tui-dui",
    "totalTasks": 3,
    "tasks": [
      {
        "id": "US-001",
        "title": "Add new todo items",
        "status": "completed",
        "completedInSession": true
      }
    ]
  },
  "iterations": [],
  "skippedTaskIds": [],
  "cwd": "/path/to/project",
  "activeTaskIds": ["US-002"]
}

Common Session Issues

If the lock file refers to a dead process:

Bash

# Check if the process exists
ps -p $(cat .ralph-tui/ralph.lock | jq -r '.pid')
 
# Force resume if it doesn't
ralph-tui resume --force

Configuration Debugging

View Effective Configuration

Bash

# See the merged configuration from all sources
ralph-tui config show

This shows the final configuration after merging:

Default values
Global config (~/.config/ralph-tui/config.toml)
Project config (.ralph-tui/config.toml)
CLI flags

Validate TOML Syntax

TOML syntax errors can cause configuration issues:

Bash

# Check for TOML parsing errors
cat .ralph-tui/config.toml | npx toml2json 2>&1

Common TOML mistakes:

Missing quotes around strings with special characters
Incorrect table nesting with [section]
Using = instead of : (TOML uses =)

Configuration Precedence

CLI Flags (highest priority)
    ↓
Project Config (.ralph-tui/config.toml)
    ↓
Global Config (~/.config/ralph-tui/config.toml)
    ↓
Default Values (lowest priority)

Agent Debugging

Verify Agent Installation

Bash

# List detected agents
ralph-tui plugins agents
 
# Test agent directly
which claude && claude --version
which opencode && opencode --version

Test Agent Execution

Run the agent manually to isolate issues:

Bash

# Test Claude Code directly
echo "Say hello" | claude --print
 
# Test OpenCode directly
echo "Say hello" | opencode run

View Agent Command

To see what command Ralph TUI executes:

Check iteration logs for the full command
Look for the command field in log JSON

Bash

ralph-tui logs --iteration 1 --verbose | head -50

Tracker Debugging

prd.json Issues

Bash

# Validate JSON syntax
cat prd.json | jq . 2>&1
 
# Check task structure
cat prd.json | jq '.userStories[] | {id, title, passes, status}'
 
# Find blocked tasks
cat prd.json | jq '.userStories[] | select(.blockedBy | length > 0)'

Beads Issues

Bash

# Check Beads status
bd doctor
 
# View all tasks in an epic
bd list --epic your-epic-id
 
# Check for blocked tasks
bd blocked
 
# Sync status
bd sync --status

Beads-bv Issues

Bash

# Verify bv is available
which bv
 
# Check graph analysis
bv --robot-triage | jq '.quick_ref'
 
# View dependency cycles (can block progress)
bv --robot-insights | jq '.Cycles'

Template Debugging

View Current Template

Bash

# Display the active prompt template
ralph-tui template show

Test Template Rendering

To see what prompt is actually sent to the agent:

Check iteration logs - the rendered prompt is included
Look for prompt or input fields in the log JSON

Template Variables

Available Handlebars variables:

{{task.id}} - Task identifier
{{task.title}} - Task title
{{task.description}} - Full description
{{task.acceptanceCriteria}} - Acceptance criteria
{{recentProgress}} - Cross-iteration context
{{epic.title}} - Epic title (if using Beads)

Progress File Debugging

The progress file tracks cross-iteration context.

View Progress History

Bash

# View accumulated progress
cat .ralph-tui/progress.md
 
# Check file size (capped at ~50KB)
ls -la .ralph-tui/progress.md

Reset Progress

If progress context is causing issues:

Bash

# Clear progress file
echo "" > .ralph-tui/progress.md
 
# Or remove entirely (will be recreated)
rm .ralph-tui/progress.md

Common Debug Workflows

Workflow: Task Won't Complete

Check iteration logs

Bash

ralph-tui logs --task TASK-ID --verbose

Look for the <promise>COMPLETE</promise> token in output.

Verify template includes completion instruction

Bash

ralph-tui template show | grep -i "promise\|complete"

Test agent directly

Run the agent manually with the same prompt to see if it completes.

Check acceptance criteria

If criteria are impossible to meet, the agent may never signal completion.

Workflow: Unexpected Behavior

Check configuration

Bash

ralph-tui config show

Verify settings match your expectations.

Review session state

Bash

ralph-tui status --json

Examine recent iterations

Bash

ralph-tui logs --verbose

Check for dependency issues

Bash

# For Beads
bd blocked
 
# For prd.json
cat prd.json | jq '.userStories[] | select(.blockedBy | length > 0)'

Workflow: Agent Errors

Check agent is working

Bash

echo "Hello" | claude --print

Verify credentials

Bash

# Claude Code
claude config show
 
# Environment
echo $ANTHROPIC_API_KEY

Check rate limits

Look for rate limit messages in iteration logs.

Review error handling config

TOML

[errorHandling]
strategy = "retry"
maxRetries = 3

Reporting Issues

When reporting issues to GitHub, include:

Ralph TUI version:
Bash
ralph-tui --version
Configuration (sanitized):
Bash
ralph-tui config show
Relevant iteration logs (remove sensitive data)
Session status:
Bash
ralph-tui status --json
Steps to reproduce the issue

INFO

Before sharing logs, remove any API keys, passwords, or other sensitive information.

Next Steps

Common Issues - Solutions for frequent problems
Configuration Reference - All configuration options
CLI Commands - Command reference