Ralph Wiggum UI

A visual Kanban UI for autonomous AI coding with Claude Code.

Ralph Wiggum UI helps you manage coding tasks that Claude Code executes autonomously. Add tasks to your backlog, and let Claude work through them one by one - or enable "AFK Mode" to run multiple tasks while you're away.

Quick Start

# In any coding project
npx ralph-wiggum-ui init

# Open the web UI
npx ralph-wiggum-ui

Requirements

• Node.js 18+
• Claude Code CLI installed and authenticated
• Git initialized in your project

Commands

Initialize

npx ralph-wiggum-ui init

Creates a .ralph-wiggum-ui/ folder in your project with:

• config.json - Project configuration
• prd.json - Task list (PRD = Product Requirements Document)
• prompt.md - Instructions for Claude
• AGENTS.md - Project guide for AI agents
• progress.txt - Learning log across iterations
• logs/ - Execution logs

Open Web UI

npx ralph-wiggum-ui
# or
npx ralph-wiggum-ui serve

Opens a Kanban board at http://localhost:3210 where you can:

• Drag and drop tasks between columns
• Add new tasks
• View real-time logs
• Start single tasks or AFK mode

Add Tasks

# Interactive mode
npx ralph-wiggum-ui add

# Quick add
npx ralph-wiggum-ui add "Implement user authentication"

# With description and criteria
npx ralph-wiggum-ui add "Add dark mode" \
  --description "Add a theme toggle to the settings page" \
  --criteria "Toggle persists across sessions" \
  --criteria "Respects system preference"

Run Tasks

# Run the next pending task
npx ralph-wiggum-ui run

# Run next 3 tasks
npx ralph-wiggum-ui run 3

# AFK Mode - run all pending tasks
npx ralph-wiggum-ui run --all

# Continue even if a task fails
npx ralph-wiggum-ui run --all --no-stop-on-failure

Check Status

npx ralph-wiggum-ui status

List Tasks

# All tasks
npx ralph-wiggum-ui list

# Filter by status
npx ralph-wiggum-ui list --status pending
npx ralph-wiggum-ui list --status completed

How It Works

1. Add tasks to your backlog via CLI or web UI
2. Run starts Claude Code with your project context
3. Claude reads the task from prd.json and implements it
4. When done, Claude outputs <TASK_STATUS>completed</TASK_STATUS>
5. The task is marked complete and the next one begins (in AFK mode)

Task Completion

A task is considered complete when:

• Claude outputs the completion tag: <TASK_STATUS>completed</TASK_STATUS>
• The process exits successfully

Progress Tracking

After each task, Claude appends learnings to progress.txt. This file persists patterns and gotchas discovered during implementation, helping future iterations avoid the same mistakes.

Project Structure

your-project/
├── .ralph-wiggum-ui/
│   ├── config.json      # Project settings
│   ├── prd.json         # Task list
│   ├── prompt.md        # Claude instructions
│   ├── AGENTS.md        # Project guide
│   ├── progress.txt     # Learnings log
│   └── logs/            # Execution logs
│       └── US-001_2024-01-15T10-30-00.log
└── ... your code

Configuration

Edit .ralph-wiggum-ui/config.json:

{
  "version": "1.0.0",
  "project": "my-app",
  "sourceDir": "src",
  "commands": {
    "test": "npm test",
    "build": "npm run build",
    "typecheck": "npm run typecheck"
  },
  "claude": {
    "model": "opus"
  },
  "afk": {
    "stopOnFailure": true,
    "notifications": true
  },
  "logs": {
    "retention": 50
  }
}

Works With Any Language

Ralph Wiggum UI works with any coding project - not just JavaScript/TypeScript. Use it with:

• Python
• Go
• Rust
• Ruby
• Java
• Or any other language

Just configure the appropriate test/build commands in your config.json.

Web UI Features

• Kanban Board: Drag tasks between Backlog, In Progress, Completed, and Failed
• AI Task Generation: Describe a feature in plain English, get atomic tasks with acceptance criteria
• Run Any Task: Click on a task and run it out of order - no need to follow the queue
• Real-time Logs: Watch Claude's output as it works
• AFK Mode: Run all pending tasks with one click
• Live Progress: See which task is running and how many are complete
• Task Details: Click any task to view logs, status, and error messages

Tips

1. Write clear tasks: Include specific acceptance criteria
2. Keep tasks small: One feature or fix per task
3. Check progress.txt: Review learnings before adding similar tasks
4. Use AFK mode wisely: Start with a few tasks to verify quality

Troubleshooting

"Claude Code not found"

Make sure Claude Code CLI is installed:

claude --version

"Not a git repository"

Initialize git in your project:

git init

Tasks failing repeatedly

Check the logs in .ralph-wiggum-ui/logs/ to see what went wrong. You may need to:

• Simplify the task
• Add more context to the description
• Fix issues in your codebase first

License

MIT