setup

Synopsis

ralph-tui setup

The setup command runs an interactive wizard that configures Ralph TUI for your project. It detects available agents, creates configuration files, and installs bundled skills.

Aliases

ralph-tui init    # Same as setup

What Setup Does

The interactive wizard performs these steps:

Examples

Basic Setup

cd your-project
ralph-tui setup

Example interaction:

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

Configuration Created

Setup creates .ralph-tui/config.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

Skills Installation

Skills are installed to your agent's skills directory:

Skipping Setup

If you want to run Ralph without the interactive setup:

# 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

Re-running Setup

You can run setup again to update your configuration:

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

Troubleshooting

"No agents found"

Ensure you have at least one supported agent installed:

# 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

"Permission denied" for skills

Ensure the skills directory is writable:

# Check which directory skills are installed to
ralph-tui skills list
 
# Create skills directory if needed (for Claude Code)
mkdir -p ~/.claude/skills

Using Skills Directly

After running ralph-tui setup, the installed skills can be used directly in your preferred AI agent without needing the Ralph TUI interface. This is ideal when you want to:

• Reference files and use agent-native features during PRD creation
• Integrate PRD creation into your existing workflow
• Use the skills as part of a larger conversation with your agent

Direct Skill Usage

Once skills are installed, invoke them with slash commands in your agent:

# In your agent, type:
/ralph-tui-prd         # Start creating a PRD interactively
/ralph-tui-create-json # Convert an existing PRD to prd.json
/ralph-tui-create-beads # Convert an existing PRD to Beads issues

Example Workflow

1. Create a PRD directly in your agent:

   Copy

   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]
   

2. Convert to tasks:

   Copy

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

3. Run Ralph for autonomous execution:

   BashCopy

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

Why Use Skills Directly?

Related Commands

• run - Start execution after setup
• create-prd - Create your first PRD
• convert - Convert existing PRDs to tasks