Orchestrate autonomous AI coding agents with the Ralph Wiggum Loop technique
npm install ralph-uiA modern application for orchestrating autonomous AI coding agents using the Ralph Wiggum Loop technique. Access via browser from any device on your network.
---
We are currently focusing on stability and polish. While Ralph UI is production-ready and stable, we are prioritizing:
- ✅ Bug reports and fixes
- ✅ Polish improvements (UX, performance, error handling)
- ✅ Documentation enhancements
- ✅ Test coverage
⏸️ Feature requests: We're collecting ideas for Phase 2! Please use the feature-request issue template - we'll review after Phase 1 completion.
🤝 Contribute: See CONTRIBUTING.md for guidelines on bug fixes and polish PRs.
---
---
Ralph UI provides a beautiful, intuitive interface for the Ralph Wiggum Loop - an autonomous AI development technique that enables AI agents to work continuously on software development tasks using the filesystem and git history as long-term memory.
- Browser Access - Access from any device on your network via HTTP/WebSocket
- Remote Terminal Access - Access from phones, tablets, or any device via your network or tunnels
- Mission Control - Bird's-eye view of all projects and active agents
- Multi-Project Support - Manage multiple projects with VS Code-style project switching
- Multi-Agent Orchestration - Run multiple AI agents in parallel with complete isolation
- Real-Time Monitoring - Watch your agents work with live terminal output and status updates
- AI-Powered PRD Creation - Interactive chat interface for creating PRDs with AI assistance
- Git Integration - Automatic worktree management, branching, and PR creation
- Cost Tracking - Monitor token usage and costs across all agents
- Session Persistence - Pause, resume, and recover sessions at any time
- PRD Management - Create PRDs from templates with quality scoring and one-click execution
---
Frontend:
- React 19 with TypeScript
- Tailwind CSS + shadcn/ui
- Zustand for state management
- xterm.js for terminal emulation
Backend:
- Rust with Axum HTTP/WebSocket server
- File-based JSON storage in .ralph-ui/
- git2-rs for git operations
- tokio for async I/O
- portable-pty for terminal emulation
Development:
- Bun for fast package management
- Vite for blazing-fast builds
- Vitest for unit testing, markdown E2E tests with LLM browser automation
---
The fastest way to run Ralph UI - no cloning or building required:
``bashRun Ralph UI instantly
npx ralph-ui
The binary is downloaded once and cached in
.Supported platforms: macOS (Intel/Apple Silicon), Linux (x64/arm64), Windows
---
Getting Started
$3
- Rust: 1.75+ (install from rustup.rs)
- Bun: 1.2+ (recommended) or Node.js 18+
$3
Option 1: NPX (Recommended)
`bash
npx ralph-ui
`That's it! The server starts on port 3420. Open
and enter the auth token.Option 2: From Source (Development)
`bash
Clone the repository
git clone https://github.com/dario-valles/Ralph-UI.git
cd Ralph-UIInstall dependencies
bun installStart the backend server (Terminal 1)
bun run server:devStart the frontend dev server (Terminal 2)
bun run devOpen http://localhost:1420 in your browser
Enter the auth token displayed by the server
`Testing & Building
bash
bun run test # Frontend tests
bun run cargo:test # Backend tests
bun run cargo:build # Backend binary
bun run build # Frontend assets
`See QUICK_START.md for detailed setup instructions.
---
Documentation
- Quick Start Guide - Developer setup and getting started
- Project Structure - File organization and architecture
- CLAUDE.md - Detailed development instructions and commands
---
What is the Ralph Wiggum Loop?
> Trademark Notice: "Ralph Wiggum" is a trademark of 20th Century Fox.
> This project uses the term nominally to describe the AI development technique
> coined by Geoffrey Huntley. We are not affiliated with or endorsed by Fox.
The Ralph Wiggum Loop is an autonomous AI development technique where:
1. Infinite Iteration: AI agents run in loops until all tasks are complete
2. Filesystem Memory: Progress persists in files and git history, not LLM context
3. Fresh Context: When context fills up, a new agent starts with fresh memory
4. Autonomous Operation: Agents can work for hours without human intervention
Originally coined by Geoffrey Huntley, this technique represents a paradigm shift in AI-assisted development, with community members reporting 14+ hour autonomous sessions successfully upgrading entire codebases.
---
Supported AI Agents
Ralph UI supports 7 production-ready AI coding agents with full session management and token optimization:
- Claude Code (Anthropic's official CLI) - Fully integrated with session resumption
- OpenCode (Open source alternative) - Fully integrated with resume support
- Cursor Agent - Integrated with session resume capability
- Codex CLI (OpenAI) - Integrated with session resume support
- Qwen Code (Alibaba) - Integrated with Claude-compatible API
- Droid (Factory AI) - Integrated with CLI session management
- gemini-cli (Google) - Integrated with Gemini models
$3
For Claude Code, Ralph UI supports alternative API providers that offer Claude-compatible endpoints:
- Anthropic (Direct) - Default provider using official Anthropic API
- Z.AI - Claude-compatible API with alternative pricing
- MiniMax - Claude-compatible API service
- MiniMax (China) - China-specific endpoint for MiniMax service
Provider Configuration:
- Configure providers in Settings → API Providers
- Add API tokens for each provider you want to use
- Test connections directly from the UI
- Set a default provider for all Claude operations
Usage:
- When selecting agents, choose "Claude (Z.AI)" or "Claude (MiniMax)" from the dropdown
- The agent/model selector displays available providers once configured
- All Claude features work identically across providers
- Environment variables are automatically set when spawning agents
Benefits:
- Access Claude models through alternative providers
- Potential cost savings depending on provider pricing
- Geographic optimization (e.g., MiniMax China for Asia-Pacific users)
- Easy provider switching without code changes
$3
Ralph UI uses native CLI session resumption to avoid re-sending full conversation history on each message, providing 67-90% token savings depending on conversation length.
How it works:
1. First message: Full prompt sent, agent's session ID captured from output
2. Subsequent messages: Session ID passed via resume flag, history omitted from prompt
3. The CLI agent maintains its own context, so history isn't needed
Supported agents with resume flags:
- Claude Code (
)
- Cursor Agent (--resume=)
- Codex CLI (codex resume )
- Qwen Code (--continue)
- OpenCode (--session )
- Droid (--session-id )
- gemini-cli (check documentation for resume support)Token savings by conversation length:
| Messages | Without Resume | With Resume | Savings |
|----------|----------------|-------------|---------|
| 5 | 15 exchanges | 5 exchanges | 67% |
| 10 | 55 exchanges | 10 exchanges| 82% |
| 20 | 210 exchanges | 20 exchanges| 90% |
---
Advanced Features
$3
Preview execution without spawning agents or creating branches. Toggle in the PRD Execution dialog to validate your PRD and configuration before committing resources.$3
Reference file contents in prompts using @filename syntax:
`
Check @README.md for project context
Look at @src/main.rs for the entry point
Files are automatically injected into agent prompts.$3
Sessions persist progress to directories within each project for recovery after interruptions. Tracks task state changes with timestamps.$3
Signal handlers (SIGINT, SIGTERM, SIGHUP) ensure clean shutdown:
- Stops all running agents
- Cleans up worktrees
- Preserves committed branches$3
`bash
bun run server # Production server (port 3420)
bun run server:dev # Development mode (faster builds)
bun run server:dev:token # Dev mode with fixed token (persists across restarts)
`$3
| Feature | Status |
|---------|--------|
| All UI features | ✓ |
| Real-time events (WebSocket) | ✓ |
| Live terminal output (WebSocket PTY) | ✓ |
| File watching | ✓ |
| Directory browser | ✓ |
See CLAUDE.md for detailed server documentation including authentication, endpoints, and architecture.
---
Remote Terminal Access
Ralph UI runs as an HTTP/WebSocket server, accessible from any device on your network or remotely via tunnels.
$3
bash
Start server (binds to all interfaces by default)
npx ralph-uiOr specify port
npx ralph-ui --port 8080
`Access from any device:
- Find your IP: (macOS) or hostname -I (Linux)
- Enter the auth token shown in the terminal$3
For access outside your network:
`bash
Using ngrok
ngrok http 3420Using Cloudflare Tunnel
cloudflared tunnel --url http://localhost:3420Using Tailscale (recommended for persistent access)
Install Tailscale, then access via your Tailscale IP
`$3
- Always use a strong
for remote access
- Consider HTTPS proxy for public tunnels
- The default token is regenerated on each restart; use --token for persistence---
Architecture
`
┌─────────────────────────────────────────────────────────┐
│ Ralph UI │
├─────────────────────────────────────────────────────────┤
│ Frontend (React + TypeScript) │
│ - Mission Control with multi-project overview │
│ - Task list with dependency tracking │
│ - Agent monitor with live terminal output │
│ - PRD creation with AI chat interface │
│ - Git timeline and PR management │
├─────────────────────────────────────────────────────────┤
│ Backend (Rust + Axum) │
│ - HTTP/WebSocket server │
│ - Task engine (PRD parsing, state tracking) │
│ - Git manager (worktrees, branches, commits) │
│ - Agent manager (spawn, monitor, kill, PTY) │
│ - File storage (.ralph-ui/ JSON files) │
├─────────────────────────────────────────────────────────┤
│ External Integrations │
│ - Claude Code CLI, OpenCode CLI │
│ - GitHub API (Issues, PRs) │
└─────────────────────────────────────────────────────────┘
---
Deployment
$3
dockerfile
FROM rust:latest AS builder
WORKDIR /app
COPY server .
RUN cargo build --releaseFROM debian:bookworm-slim
COPY --from=builder /app/target/release/ralph-ui /usr/local/bin/
EXPOSE 3420
CMD ["ralph-ui", "--bind", "0.0.0.0"]
`$3
bash
Build release binary (14MB)
bun run cargo:buildRun directly
./server/target/release/ralph-ui --port 3420 --bind 0.0.0.0
`---
Related Projects
- ralph-tui - Terminal UI implementation (TypeScript/Bun)
- ralphy - Bash automation tool for Ralph Loop
- ralph - Autonomous AI agent loop CLI
Ralph UI aims to provide the most comprehensive graphical interface for the Ralph ecosystem.
---
Contributing
We welcome contributions! This project is in active development.
$3
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
1. Check the Project Structure to understand the codebase
2. Look for issues tagged with
or help-wanted`---
| Metric | Target |
|--------|--------|
| Binary Size | ~14 MB |
| Startup Time | < 1s |
| Memory Usage | < 100 MB idle, < 300 MB with 5 agents |
| UI Responsiveness | < 100ms for all interactions |
---
This project is licensed under the MIT License - see the LICENSE file for details.
---
- Geoffrey Huntley for pioneering the Ralph Wiggum Loop technique
- Anthropic for Claude Code and official Ralph Wiggum plugin
- ralph-tui team for inspiration and architectural patterns
---
Built with Rust, Axum, React, and TypeScript
Making autonomous AI development accessible, transparent, and delightful.