Ralph Dashboard

A web dashboard for monitoring and managing Ralph Wiggum loops.

Features

• View Active Loops: See all currently running Ralph Wiggum loops in real-time
• Loop History: Browse archived loops with statistics and details
• Cancel Loops: Stop active loops directly from the dashboard
• Delete History: Permanently remove archived loops from history
• Statistics: Track success rates, durations, and iteration counts

Installation

# Using bun (recommended)
bunx ralph-dashboard

# Using npm
npx ralph-dashboard

Options

# Custom port
bunx ralph-dashboard --port 8080
bunx ralph-dashboard -p 8080

# Public access (bind to all interfaces)
bunx ralph-dashboard --host 0.0.0.0
bunx ralph-dashboard -h 0.0.0.0

# Both options
bunx ralph-dashboard -p 8080 -h 0.0.0.0

# Show help
bunx ralph-dashboard --help

Once running, open your browser to the displayed URL (default: http://localhost:3847).

Development

Prerequisites

• Bun runtime

Setup

# Install dependencies
bun install

# Start development server (frontend only)
bun run dev

# Start backend server
bun run dev:server

# Run tests
bun run test

# Run tests with coverage
bun run test:coverage

# Run e2e tests
bun run test:e2e

# Run e2e tests in UI mode
bun run test:e2e:ui

# Type check
bun run typecheck

# Build for production
bun run build

Project Structure

ralph-dashboard/
├── src/                    # Frontend React app
│   ├── components/         # React components
│   ├── hooks/              # React Query hooks
│   ├── lib/                # API client
│   └── __tests__/          # Frontend unit tests
├── server/                 # Backend Bun server
│   ├── api/                # API route handlers
│   ├── services/           # Business logic
│   └── __tests__/          # Backend unit tests
├── tests/
│   └── e2e/                # Playwright e2e tests
└── dist/                   # Production build

API Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/sessions | List all sessions | | GET | /api/sessions/:id | Get session details | | POST | /api/sessions/:id/cancel | Cancel an active session | | POST | /api/sessions/:id/archive | Archive an orphaned session | | DELETE | /api/sessions/:id | Permanently delete an archived session | | GET | /api/transcript/iterations/:loopId | Get paginated iteration transcripts | | GET | /api/transcript/full/:loopId | Get full transcript with user prompt | | GET | /api/transcript/check/:loopId | Check if transcript exists | | GET | /api/checklist/:loopId | Get checklist progress for a loop |

Data Sources

The dashboard reads from the following files in ~/.claude/ralph-wiggum-pro/:

| Directory | Purpose | |-----------|---------| | loops/ | Active loop state files (frontmatter + prompt) | | logs/sessions.jsonl | Session history (JSONL format) | | transcripts/ | Iteration and full transcript files |

Requirements

• Ralph Wiggum Pro plugin must be installed and configured
• Sessions are logged to ~/.claude/ralph-wiggum-pro/logs/sessions.jsonl
• State files stored in ~/.claude/ralph-wiggum-pro/loops/

License

MIT