ralph-tui-create-beads-rust

by @subsy in Productivity

1,500

147

# Install this skill:

npx skills add subsy/ralph-tui

Or install specific skill: npx add-skill https://github.com/subsy/ralph-tui/tree/main/skills/ralph-tui-create-beads-rust

# Description

Convert PRDs to beads for ralph-tui execution using beads-rust (br CLI). Creates an epic with child beads for each user story. Use when you have a PRD and want to use ralph-tui with beads-rust as the task source. Triggers on: create beads, convert prd to beads, beads for ralph, ralph beads, br beads.

# SKILL.md

name: ralph-tui-create-beads-rust
description: "Convert PRDs to beads for ralph-tui execution using beads-rust (br CLI). Creates an epic with child beads for each user story. Use when you have a PRD and want to use ralph-tui with beads-rust as the task source. Triggers on: create beads, convert prd to beads, beads for ralph, ralph beads, br beads."

Ralph TUI - Create Beads (beads-rust)

Converts PRDs to beads (epic + child tasks) for ralph-tui autonomous execution using beads-rust (br CLI).

Note: This skill uses the br command from beads-rust. If you have the original beads (bd) installed instead, use the ralph-tui-create-beads skill.

The Job

Take a PRD (markdown file or text) and create beads using br commands:
1. Extract Quality Gates from the PRD's "Quality Gates" section
2. Create an epic bead for the feature
3. Create child beads for each user story (with quality gates appended)
4. Set up dependencies between beads (schema → backend → UI)
5. Output ready for ralph-tui run --tracker beads-rust

Step 1: Extract Quality Gates

Look for the "Quality Gates" section in the PRD:

## Quality Gates

These commands must pass for every user story:
- `pnpm typecheck` - Type checking
- `pnpm lint` - Linting

For UI stories, also include:
- Verify in browser using dev-browser skill

Extract:
- Universal gates: Commands that apply to ALL stories (e.g., pnpm typecheck)
- UI gates: Commands that apply only to UI stories (e.g., browser verification)

If no Quality Gates section exists: Ask the user what commands should pass, or use a sensible default like npm run typecheck.

Output Format

Beads use br create command with HEREDOC syntax to safely handle special characters:

# Create epic (link back to source PRD)
br create --type=epic \
  --title="[Feature Name]" \
  --description="$(cat <<'EOF'
[Feature description from PRD]
EOF
)" \
  --external-ref="prd:./tasks/feature-name-prd.md"

# Create child bead (with quality gates in acceptance criteria)
br create \
  --parent=EPIC_ID \
  --title="[Story Title]" \
  --description="$(cat <<'EOF'
[Story description with acceptance criteria INCLUDING quality gates]
EOF
)" \
  --priority=[1-4]

CRITICAL: Always use <<'EOF' (single-quoted) for the HEREDOC delimiter. This prevents shell interpretation of backticks, $variables, and () in descriptions.

Story Size: The #1 Rule

Each story must be completable in ONE ralph-tui iteration (~one agent context window).

ralph-tui spawns a fresh agent instance per iteration with no memory of previous work. If a story is too big, the agent runs out of context before finishing.

Right-sized stories:

Add a database column + migration
Add a UI component to an existing page
Update a server action with new logic
Add a filter dropdown to a list

Too big (split these):

"Build the entire dashboard" → Split into: schema, queries, UI components, filters
"Add authentication" → Split into: schema, middleware, login UI, session handling
"Refactor the API" → Split into one story per endpoint or pattern

Rule of thumb: If you can't describe the change in 2-3 sentences, it's too big.

Story Ordering: Dependencies First

Stories execute in dependency order. Earlier stories must not depend on later ones.

Correct order:
1. Schema/database changes (migrations)
2. Server actions / backend logic
3. UI components that use the backend
4. Dashboard/summary views that aggregate data

Wrong order:
1. ❌ UI component (depends on schema that doesn't exist yet)
2. ❌ Schema change

Dependencies with `br dep add`

Use the br dep add command to specify which beads must complete first:

# Create the beads first
br create --parent=epic-123 --title="US-001: Add schema" ...
br create --parent=epic-123 --title="US-002: Create API" ...
br create --parent=epic-123 --title="US-003: Build UI" ...

# Then add dependencies (issue depends-on blocker)
br dep add ralph-tui-002 ralph-tui-001  # US-002 depends on US-001
br dep add ralph-tui-003 ralph-tui-002  # US-003 depends on US-002

Syntax: br dep add <issue> <depends-on> — the issue depends on (is blocked by) depends-on.

ralph-tui will:
- Show blocked beads as "blocked" until dependencies complete
- Never select a bead for execution while its dependencies are open
- Include dependency context in the prompt when working on a bead

Correct dependency order:
1. Schema/database changes (no dependencies)
2. Backend logic (depends on schema)
3. UI components (depends on backend)
4. Integration/polish (depends on UI)

Acceptance Criteria: Quality Gates + Story-Specific

Each bead's description should include acceptance criteria with:
1. Story-specific criteria from the PRD (what this story accomplishes)
2. Quality gates from the PRD's Quality Gates section (appended at the end)

Good criteria (verifiable):

"Add investorType column to investor table with default 'cold'"
"Filter dropdown has options: All, Cold, Friend"
"Clicking toggle shows confirmation dialog"

Bad criteria (vague):

❌ "Works correctly"
❌ "User can do X easily"
❌ "Good UX"
❌ "Handles edge cases"

Conversion Rules

Extract Quality Gates from PRD first
Each user story → one bead
First story: No dependencies (creates foundation)
Subsequent stories: Depend on their predecessors (UI depends on backend, etc.)
Priority: Based on dependency order, then document order (0=critical, 2=medium, 4=backlog)
All stories: status: "open"
Acceptance criteria: Story criteria + quality gates appended
UI stories: Also append UI-specific gates (browser verification)

Splitting Large PRDs

If a PRD has big features, split them:

Original:

"Add friends outreach track with different messaging"

Split into:
1. US-001: Add investorType field to database
2. US-002: Add type toggle to investor list UI
3. US-003: Create friend-specific phase progression logic
4. US-004: Create friend message templates
5. US-005: Wire up task generation for friends
6. US-006: Add filter by type
7. US-007: Update new investor form
8. US-008: Update dashboard counts

Each is one focused change that can be completed and verified independently.

Example

Input PRD:

# PRD: Friends Outreach

Add ability to mark investors as "friends" for warm outreach.

## Quality Gates

These commands must pass for every user story:
- `pnpm typecheck` - Type checking
- `pnpm lint` - Linting

For UI stories, also include:
- Verify in browser using dev-browser skill

## User Stories

### US-001: Add investorType field to investor table
**Description:** As a developer, I need to categorize investors as 'cold' or 'friend'.

**Acceptance Criteria:**
- [ ] Add investorType column: 'cold' | 'friend' (default 'cold')
- [ ] Generate and run migration successfully

### US-002: Add type toggle to investor list rows
**Description:** As Ryan, I want to toggle investor type directly from the list.

**Acceptance Criteria:**
- [ ] Each row has Cold | Friend toggle
- [ ] Switching shows confirmation dialog
- [ ] On confirm: updates type in database

### US-003: Filter investors by type
**Description:** As Ryan, I want to filter the list to see just friends or cold.

**Acceptance Criteria:**
- [ ] Filter dropdown: All | Cold | Friend
- [ ] Filter persists in URL params

Output beads:

# Create epic (link back to source PRD)
br create --type=epic \
  --title="Friends Outreach Track" \
  --description="$(cat <<'EOF'
Warm outreach for deck feedback
EOF
)" \
  --external-ref="prd:./tasks/friends-outreach-prd.md"

# US-001: No deps (first - creates schema)
br create --parent=ralph-tui-abc \
  --title="US-001: Add investorType field to investor table" \
  --description="$(cat <<'EOF'
As a developer, I need to categorize investors as 'cold' or 'friend'.

## Acceptance Criteria
- [ ] Add investorType column: 'cold' | 'friend' (default 'cold')
- [ ] Generate and run migration successfully
- [ ] pnpm typecheck passes
- [ ] pnpm lint passes
EOF
)" \
  --priority=1

# US-002: UI story (gets browser verification too)
br create --parent=ralph-tui-abc \
  --title="US-002: Add type toggle to investor list rows" \
  --description="$(cat <<'EOF'
As Ryan, I want to toggle investor type directly from the list.

## Acceptance Criteria
- [ ] Each row has Cold | Friend toggle
- [ ] Switching shows confirmation dialog
- [ ] On confirm: updates type in database
- [ ] pnpm typecheck passes
- [ ] pnpm lint passes
- [ ] Verify in browser using dev-browser skill
EOF
)" \
  --priority=2

# Add dependency: US-002 depends on US-001
br dep add ralph-tui-002 ralph-tui-001

# US-003: UI story
br create --parent=ralph-tui-abc \
  --title="US-003: Filter investors by type" \
  --description="$(cat <<'EOF'
As Ryan, I want to filter the list to see just friends or cold.

## Acceptance Criteria
- [ ] Filter dropdown: All | Cold | Friend
- [ ] Filter persists in URL params
- [ ] pnpm typecheck passes
- [ ] pnpm lint passes
- [ ] Verify in browser using dev-browser skill
EOF
)" \
  --priority=3

# Add dependency: US-003 depends on US-002
br dep add ralph-tui-003 ralph-tui-002

Syncing Changes

After creating beads, sync to export to JSONL (for git tracking):

br sync --flush-only

This exports the SQLite database to .beads/issues.jsonl for version control.

Output Location

Beads are stored in: .beads/ directory (SQLite DB + JSONL export)

After creation, run ralph-tui:

# Work on a specific epic
ralph-tui run --tracker beads-rust --epic ralph-tui-abc

# Or let it pick the best task automatically
ralph-tui run --tracker beads-rust

ralph-tui will:
1. Work on beads within the specified epic (or select the best available task)
2. Close each bead when complete
3. Close the epic when all children are done
4. Output <promise>COMPLETE</promise> when epic is done

Checklist Before Creating Beads

[ ] Extracted Quality Gates from PRD (or asked user if missing)
[ ] Each story is completable in one iteration (small enough)
[ ] Stories are ordered by dependency (schema → backend → UI)
[ ] Quality gates appended to every bead's acceptance criteria
[ ] UI stories have browser verification (if specified in Quality Gates)
[ ] Acceptance criteria are verifiable (not vague)
[ ] No story depends on a later story (only earlier stories)
[ ] Dependencies added with br dep add after creating beads
[ ] Ran br sync --flush-only to export for git tracking

Differences from beads (Go version)

Command	beads (`bd`)	beads-rust (`br`)
Create	`bd create`	`br create`
Dependencies	`bd dep add`	`br dep add`
Sync	`bd sync`	`br sync --flush-only`
Close	`bd close`	`br close`
Storage	`.beads/beads.jsonl`	`.beads/*.db` + JSONL export

# README.md

Ralph TUI

AI Agent Loop Orchestrator - A terminal UI for orchestrating AI coding agents to work through task lists autonomously.

Ralph TUI connects your AI coding assistant (Claude Code, OpenCode, Factory Droid, Gemini CLI, Codex, Kiro CLI) to your task tracker and runs them in an autonomous loop, completing tasks one-by-one with intelligent selection, error handling, and full visibility.

Ralph TUI Screenshot

Quick Start

# Install
bun install -g ralph-tui

# Setup your project
cd your-project
ralph-tui setup

# Create a PRD with AI assistance
ralph-tui create-prd --chat

# Run Ralph!
ralph-tui run --prd ./prd.json

That's it! Ralph will work through your tasks autonomously.

Documentation

ralph-tui.com - Full documentation, guides, and examples.

Quick Links

Quick Start Guide - Get running in 2 minutes
Installation - All installation options
CLI Reference - Complete command reference
Configuration - Customize Ralph for your workflow
Troubleshooting - Common issues and solutions

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐   │
│   │  1. SELECT   │────▶│  2. BUILD    │────▶│  3. EXECUTE  │   │
│   │    TASK      │     │    PROMPT    │     │    AGENT     │   │
│   └──────────────┘     └──────────────┘     └──────────────┘   │
│          ▲                                         │            │
│          │                                         ▼            │
│   ┌──────────────┐                         ┌──────────────┐    │
│   │  5. NEXT     │◀────────────────────────│  4. DETECT   │    │
│   │    TASK      │                         │  COMPLETION  │    │
│   └──────────────┘                         └──────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Ralph selects the highest-priority task, builds a prompt, executes your AI agent, detects completion, and repeats until all tasks are done.

Features

Task Trackers: prd.json (simple), Beads (git-backed with dependencies)
AI Agents: Claude Code, OpenCode, Factory Droid, Gemini CLI, Codex, Kiro CLI
Session Persistence: Pause anytime, resume later, survive crashes
Real-time TUI: Watch agent output, control execution with keyboard shortcuts
Subagent Tracing: See nested agent calls in real-time
Cross-iteration Context: Automatic progress tracking between tasks
Flexible Skills: Use PRD/task skills directly in your agent or via the TUI
Remote Instances: Monitor and control ralph-tui running on multiple machines from a single TUI

CLI Commands

Command	Description
`ralph-tui`	Launch the interactive TUI
`ralph-tui run [options]`	Start Ralph execution
`ralph-tui resume`	Resume an interrupted session
`ralph-tui status`	Check session status
`ralph-tui logs`	View iteration output logs
`ralph-tui setup`	Run interactive project setup
`ralph-tui create-prd`	Create a new PRD interactively
`ralph-tui convert`	Convert PRD to tracker format
`ralph-tui config show`	Display merged configuration
`ralph-tui template show`	Display current prompt template
`ralph-tui plugins agents`	List available agent plugins
`ralph-tui plugins trackers`	List available tracker plugins
`ralph-tui run --listen`	Run with remote listener enabled
`ralph-tui remote <cmd>`	Manage remote server connections

Common Options

# Run with a PRD file
ralph-tui run --prd ./prd.json

# Run with a Beads epic
ralph-tui run --epic my-epic-id

# Override agent or model
ralph-tui run --agent claude --model sonnet
ralph-tui run --agent opencode --model anthropic/claude-3-5-sonnet

# Limit iterations
ralph-tui run --iterations 5

# Run headless (no TUI)
ralph-tui run --headless

# Run agent in isolated sandbox (bwrap on Linux, sandbox-exec on macOS)
# Requires bwrap to be installed and on PATH (Linux) or uses built-in sandbox-exec (macOS)
ralph-tui run --sandbox

# Use a bundled color theme by name
ralph-tui run --theme dracula

Create PRD Options

# Create a PRD with AI assistance (default chat mode)
ralph-tui create-prd
ralph-tui prime  # Alias

# Use a custom PRD skill from skills_dir
ralph-tui create-prd --prd-skill my-custom-skill

# Override agent
ralph-tui create-prd --agent claude

# Output to custom directory
ralph-tui create-prd --output ./docs

TUI Keyboard Shortcuts

Key	Action
`s`	Start execution
`p`	Pause/Resume
`d`	Toggle dashboard
`T`	Toggle subagent tree panel (Shift+T)
`t`	Cycle subagent detail level
`o`	Cycle right panel views
`,`	Open settings (local tab only)
`C`	Open read-only config viewer (Shift+C, works on local and remote tabs)
`q`	Quit
`?`	Show help
`1-9`	Switch to tab 1-9 (remote instances)
`[` / `]`	Previous/Next tab
`a`	Add new remote instance
`e`	Edit current remote (when viewing remote tab)
`x`	Delete current remote (when viewing remote tab)

Dashboard (d key): Toggle a status panel showing:
- Current execution status and active task
- Agent name and model (e.g., claude-code, anthropic/claude-sonnet)
- Tracker source (e.g., prd, beads)
- Git branch with dirty indicator (repo:branch*)
- Sandbox status (🔒 enabled, 🔓 disabled) with mode
- Auto-commit setting (✓ auto, ✗ manual)
- Remote connection info (when viewing remote tabs)

See the full CLI reference for all options.

Custom Themes

Ralph TUI supports custom color themes via the --theme option:

# Use a bundled theme by name
ralph-tui run --theme dracula

# Or use a custom theme file
ralph-tui run --theme ./my-custom-theme.json

Custom Theme Example

Bundled themes: bright, catppuccin, dracula, high-contrast, solarized-light

See the Themes documentation for the full theme schema and creating custom themes.

Using Skills Directly in Your Agent

Install ralph-tui skills to your agent using add-skill:

# Install all skills to all detected agents globally
bunx add-skill subsy/ralph-tui --all

# Install to a specific agent
bunx add-skill subsy/ralph-tui -a claude-code -g -y

# Or use the ralph-tui wrapper (maps agent IDs automatically)
ralph-tui skills install
ralph-tui skills install --agent claude

Use these slash commands in your agent:

/ralph-tui-prd           # Create a PRD interactively
/ralph-tui-create-json   # Convert PRD to prd.json
/ralph-tui-create-beads  # Convert PRD to Beads issues

This lets you create PRDs while referencing source files (@filename) and using your full conversation context—then use ralph-tui run for autonomous execution.

Custom Skills Directory

You can configure a custom skills_dir in your config file to use custom PRD skills:

# In .ralph-tui/config.toml or ~/.config/ralph-tui/config.toml
skills_dir = "/path/to/my-skills"

# Then use custom skills
ralph-tui create-prd --prd-skill my-custom-skill

Skills must be folders inside skills_dir containing a SKILL.md file.

Remote Instance Management

Control multiple ralph-tui instances running on different machines (VPS servers, CI/CD environments, development boxes) from a single TUI.

┌─────────────────────────────────────────────────────────────────┐
│  LOCAL [1]│ ● prod [2]│ ◐ staging [3]│ ○ dev [4]│      +       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   Your local TUI can connect to and control remote instances    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Start: Remote Control

On the remote machine (server):

# Start ralph with remote listener enabled
ralph-tui run --listen --prd ./prd.json

# First run generates a secure token - save it!
# ═══════════════════════════════════════════════════════════════
#                    Remote Listener Enabled
# ═══════════════════════════════════════════════════════════════
#   Port: 7890
#   New server token generated:
#   OGQwNTcxMjM0NTY3ODkwYWJjZGVmMDEyMzQ1Njc4OQ
#   ⚠️  Save this token securely - it won't be shown again!
# ═══════════════════════════════════════════════════════════════

On your local machine (client):

# Add the remote server
ralph-tui remote add prod server.example.com:7890 --token OGQwNTcxMjM0NTY3...

# Test the connection
ralph-tui remote test prod

# Launch TUI - you'll see tabs for local + remote instances
ralph-tui

Remote Listener Commands

Recommended: Use run --listen (runs engine with remote access):

# Start with remote listener on default port (7890)
ralph-tui run --listen --prd ./prd.json

# Start with custom port
ralph-tui run --listen --listen-port 8080 --epic my-epic

Token management:

# Rotate authentication token (invalidates old token immediately)
ralph-tui run --listen --rotate-token --prd ./prd.json

# View remote listener options
ralph-tui run --help

Remote Configuration Commands

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

# List all remotes with connection status
ralph-tui remote list

# Test connectivity to a specific remote
ralph-tui remote test <alias>

# Remove a remote
ralph-tui remote remove <alias>

# Push config to a remote (propagate your local settings)
ralph-tui remote push-config <alias>
ralph-tui remote push-config --all  # Push to all remotes

Push Configuration to Remotes

When managing multiple ralph-tui instances, you typically want them all to use the same configuration. The push-config command lets you propagate your local config to remote instances:

# Push config to a specific remote
ralph-tui remote push-config prod

# Preview what would be pushed (without applying)
ralph-tui remote push-config prod --preview

# Push to all configured remotes
ralph-tui remote push-config --all

# Force overwrite existing config without confirmation
ralph-tui remote push-config prod --force

# Push specific scope (global or project config)
ralph-tui remote push-config prod --scope global
ralph-tui remote push-config prod --scope project

How it works:
1. Reads your local config (~/.config/ralph-tui/config.toml or .ralph-tui/config.toml)
2. Connects to the remote instance
3. Checks what config exists on the remote
4. Creates a backup if overwriting (e.g., config.toml.backup.2026-01-19T12-30-00-000Z)
5. Writes the new config
6. Triggers auto-migration to install skills/templates

Scope selection:
- --scope global: Push to ~/.config/ralph-tui/config.toml on remote
- --scope project: Push to .ralph-tui/config.toml in remote's working directory
- Without --scope: Auto-detects based on what exists locally and remotely

Security Model

Ralph uses a two-tier token system for secure remote access:

Token Type	Lifetime	Purpose
Server Token	90 days	Initial authentication, stored on disk
Connection Token	24 hours	Session authentication, auto-refreshed

Security features:
- Without a token configured, the listener binds only to localhost (127.0.0.1)
- With a token configured, the listener binds to all interfaces (0.0.0.0)
- All connections require authentication
- All remote actions are logged to ~/.config/ralph-tui/audit.log
- Tokens are shown only once at generation time

Connection Resilience

Remote connections automatically handle network interruptions:

Auto-reconnect: Exponential backoff from 1s to 30s (max 10 retries)
Silent retries: First 3 retries are silent, then toast notifications appear
Status indicators: ● connected, ◐ connecting, ⟳ reconnecting, ○ disconnected
Metrics display: Latency (ms) and connection duration shown in tab bar

When connected to remote instances, a tab bar appears at the top of the TUI:

Key	Action
`1-9`	Jump directly to tab 1-9
`[`	Previous tab
`]`	Next tab
`Ctrl+Tab`	Next tab
`Ctrl+Shift+Tab`	Previous tab

The first tab is always "Local" (your current machine). Remote tabs show the alias you configured with connection status.

Managing Remotes from the TUI

You can add, edit, and delete remote servers directly from the TUI without leaving the interface:

Add Remote (a key):
Opens a form dialog to configure a new remote:
- Alias: A short name for the remote (e.g., "prod", "dev-server")
- Host: The server address (e.g., "192.168.1.100", "server.example.com")
- Port: The listener port (default: 7890)
- Token: The server token (displayed on the remote when you start with --listen)

Use Tab/Shift+Tab to move between fields, Enter to save, Esc to cancel.

Edit Remote (e key):
When viewing a remote tab, press e to edit its configuration. The form pre-fills with current values. You can change any field, including the alias.

Delete Remote (x key):
When viewing a remote tab, press x to delete it. A confirmation dialog shows the remote details before deletion.

Full Remote Control

When connected to a remote instance, you have full control:

View: Agent output, logs, progress, task list
Control: Pause, resume, cancel execution
Modify: Add/remove iterations, refresh tasks
Start: Begin new task execution

All operations work identically to local control with <100ms perceived latency.

Configuration Files

File	Purpose
`~/.config/ralph-tui/remote.json`	Server token storage
`~/.config/ralph-tui/remotes.toml`	Remote server configurations
`~/.config/ralph-tui/audit.log`	Audit log of all remote actions
`~/.config/ralph-tui/listen.pid`	Daemon PID file

Contributing

Development Setup

git clone https://github.com/subsy/ralph-tui.git
cd ralph-tui
bun install
bun run dev

Build & Test

bun run build       # Build the project
bun run typecheck   # Type check (no emit)
bun run lint        # Run linter
bun run lint:fix    # Auto-fix lint issues

Testing

bun test            # Run all tests
bun test --watch    # Run tests in watch mode
bun test --coverage # Run tests with coverage

See CONTRIBUTING.md for detailed testing documentation including:
- Test file naming conventions
- Using factories and mocks
- Writing new tests
- Coverage requirements

Pull Request Requirements

PRs must meet these requirements before being merged:
- >50% test coverage on new/changed lines (enforced by Codecov)
- Documentation updates for any new or changed features
- All CI checks passing (typecheck, lint, tests)

See CONTRIBUTING.md for full PR guidelines.

Project Structure

ralph-tui/
├── src/
│   ├── cli.tsx           # CLI entry point
│   ├── commands/         # CLI commands (run, resume, status, logs, listen, remote, etc.)
│   ├── config/           # Configuration loading and validation (Zod schemas)
│   ├── engine/           # Execution engine (iteration loop, events)
│   ├── interruption/     # Signal handling and graceful shutdown
│   ├── logs/             # Iteration log persistence
│   ├── plugins/
│   │   ├── agents/       # Agent plugins (claude, opencode)
│   │   │   └── tracing/  # Subagent tracing parser
│   │   └── trackers/     # Tracker plugins (beads, beads-bv, json)
│   ├── remote/           # Remote instance management
│   │   ├── server.ts     # WebSocket server for remote control
│   │   ├── client.ts     # WebSocket client with auto-reconnect
│   │   ├── token.ts      # Two-tier token management
│   │   ├── config.ts     # Remote server configuration (TOML)
│   │   ├── audit.ts      # JSONL audit logging
│   │   └── types.ts      # Type definitions
│   ├── session/          # Session persistence and lock management
│   ├── setup/            # Interactive setup wizard
│   ├── templates/        # Handlebars prompt templates
│   ├── chat/             # AI chat mode for PRD creation
│   ├── prd/              # PRD generation and parsing
│   └── tui/              # Terminal UI components (OpenTUI/React)
│       └── components/   # React components (TabBar, Toast, etc.)
├── skills/               # Bundled skills for PRD/task creation
│   ├── ralph-tui-prd/
│   ├── ralph-tui-create-json/
│   └── ralph-tui-create-beads/
├── website/              # Documentation website (Next.js)
└── docs/                 # Images and static assets

Key Technologies

Bun - JavaScript runtime
OpenTUI - Terminal UI framework
Handlebars - Prompt templating

See CLAUDE.md for detailed development guidelines.

Credits

Thanks to Geoffrey Huntley for the original Ralph Wiggum loop concept.

License

MIT License - see LICENSE for details.

# Supported AI Coding Agents

This skill is compatible with the SKILL.md standard and works with all major AI coding agents:

⚡ Amp 🚀 Antigravity 🤖 Claude Code 🦀 Clawdbot 📝 Codex ▶️ Cursor 🤖 Droid 💎 Gemini CLI 🐙 GitHub Copilot 🪿 Goose 📊 Kilo Code 🔧 Kiro CLI 💻 OpenCode 🦘 Roo Code 🌲 Trae 🏄 Windsurf

Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.