RalphTUI

Installation

Install Ralph TUI using bun, npm, or from source. Includes prerequisites and agent setup.

Prerequisites

Before installing Ralph TUI, ensure you have the following:

Bun Runtime

Ralph TUI requires Bun >= 1.0.0 as its runtime. While you can install the package using npm or pnpm, Bun must be installed to run ralph-tui because it uses OpenTUI, which depends on Bun's native features.

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

Verify the installation:

Bash
bun --version
# Should output 1.0.0 or higher

AI Coding Agent

Ralph TUI orchestrates AI coding agents. You'll need at least one installed:

  • Claude Code - Anthropic's official CLI for Claude
  • OpenCode - Open-source alternative supporting multiple AI providers
  • Factory Droid - Factory Droid CLI with JSONL tracing

Installation Methods

Choose your preferred installation method:

Bash
# Install globally with Bun
bun install -g ralph-tui
 
# Verify installation
ralph-tui --version

Bun is the recommended package manager for Ralph TUI as it provides the fastest installation and best runtime compatibility.

Post-Installation Setup

After installation, initialize Ralph TUI in your project:

Bash
cd your-project
ralph-tui setup

The setup wizard will:

  1. Detect agents - Find installed AI coding agents (Claude Code, OpenCode, Factory Droid)
  2. Create configuration - Generate .ralph-tui/config.toml with your preferences
  3. Install skills - Add bundled skills for PRD creation and task conversion
  4. Detect trackers - Optionally find existing prd.json or Beads setups
INFO

You can re-run ralph-tui setup --force at any time to reconfigure your project.

Verifying Installation

Run these commands to verify everything is set up correctly:

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

Managing Skills

Ralph TUI includes bundled skills for PRD creation and task conversion. Skills are installed automatically to all detected agents during setup and upgrades.

Supported Agents

AgentSkills Location
Claude Code~/.claude/skills/
OpenCode~/.opencode/skill/
Factory Droid~/.factory/skills/

Manual Management

Bash
# List bundled skills and installation status per agent
ralph-tui skills list
 
# Install skills to all detected agents
ralph-tui skills install
 
# Force reinstall (overwrite existing)
ralph-tui skills install --force
 
# Install to a specific agent only
ralph-tui skills install --agent claude
ralph-tui skills install --agent opencode
ralph-tui skills install --agent droid
 
# Install a specific skill
ralph-tui skills install ralph-tui-prd
INFO

Skills are installed automatically when you upgrade ralph-tui. The migration runs on first use after upgrade and installs skills to all your detected agents.

Troubleshooting

"Agent not found"

If Ralph TUI can't find your AI agent:

  1. Verify the agent CLI is installed: which claude or which opencode
  2. Ensure the agent is in your PATH
  3. Run ralph-tui plugins agents to see detected agents

"bun: command not found"

Bun may not be in your PATH. Try:

Bash
# Add to your shell profile (.bashrc, .zshrc, etc.)
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

Then restart your terminal or run source ~/.bashrc (or equivalent).

Permission Errors

If you encounter permission errors during global installation:

Bun installs packages to ~/.bun/install/global by default, which shouldn't require elevated permissions. If you see errors, check that directory exists and is writable:

Bash
mkdir -p ~/.bun/install/global

Next Steps

With Ralph TUI installed: