ralph-on-shelf

---

What is Ralph-On-Shelf?

Ralph-On-Shelf (ROS) is an autonomous agent system that combines Wiggum planning with Ralph execution:

1. Wiggum (local) analyzes your task, breaks it into todos, and assigns the right MCP tools
2. Ralph (in E2B sandbox) executes the plan autonomously with self-referential iteration

Think of it as Chief Wiggum dispatching Ralph to do the actual work - earnest, persistent, and quietly effective.

Architecture

                    LOCAL                          E2B CLOUD SANDBOX
                      |                                   |
User Task -----> [Wiggum Planner] -----> [Ralph Loop] -----> Results
                      |                       |
                 Creates todos           Iterates until
                 Assigns MCPs            completion or
                 Shows plan              max iterations
                      |                       |
                      v                       v
              "Search needs exa-search"   "I'm helping!"
              "File ops need nothing"     *uses tools*
                                          *writes files*
                                          *downloads output*

Key Features

Wiggum Planning (Local)

• Analyzes task complexity and breaks into 1-5 subtasks
• Assigns only the MCP tools each subtask actually needs
• Shows you the plan before execution begins
• Adjusts iteration count based on estimated complexity

Ralph Execution (Sandbox)

• Runs entirely inside isolated E2B cloud VM
• Self-referential loop (stop-hook pattern) - iterates until complete
• Access to 13+ MCP servers for external tools
• Local tools for file operations (write_file, read_file, execute_python)
• Ralph Wiggum quotes in terminal output

Available MCP Servers

Server	Type	Use Case
exa-search	open	Web search and research
tavily	api_key	AI-optimized search
aws-knowledge	open	AWS documentation
github	oauth	Repository management
notion	oauth	Workspace and docs
linear	oauth	Issue tracking
stripe	api_key	Payment processing
pinecone	api_key	Vector database
huggingface	api_key	ML models
firecrawl	api_key	Web scraping
sentry	api_key	Error tracking
posthog	api_key	Analytics
wandb	api_key	ML experiments

Quick Start

Prerequisites

• Python 3.11+
• Anthropic API key
• E2B API key
• Optional: API keys for MCP servers you want to use

Install

pip install -e .

Configure

Create .env:

ANTHROPIC_API_KEY=sk-ant-...
E2B_API_KEY=e2b_...

# Optional MCP API keys
TAVILY_API_KEY=tvly-...
GITHUB_TOKEN=ghp_...
STRIPE_API_KEY=sk_...
PINECONE_API_KEY=...

Run Directly (Python)

from main import launch_ralph

result = launch_ralph(
    prompt="Search for Python 3.13 features and create a summary file",
    max_iterations=5,
    use_wiggum=True  # Enable Wiggum planning (default)
)

Use with Claude Code (Plugin)

ROS integrates with Claude Code as a native plugin:

# Start an autonomous task
/ros "Build a REST API with tests. Output COMPLETE when done." --max-iterations 10

# List available MCP servers
/ros-mcp

# Cancel a running loop
/cancel-ros

The /ros command triggers the full Wiggum + Ralph workflow inside Claude Code.

Example Output

[wiggum] Analyzing task...

============================================================
  WIGGUM EXECUTION PLAN
============================================================

Analysis: Search for news and write summary to file.
Estimated iterations: 3

Todos:
  1. Search the web for latest Claude AI news
     MCPs: exa-search, tavily

  2. Analyze results and create summary
     MCPs: (no external tools)

  3. Write summary to file
     MCPs: (no external tools)

============================================================

[ralph] launching autonomous sandbox agent
[ralph] MCP servers: exa-search, tavily

============================================================
  RALPH LOOP - ITERATION 1/3
============================================================

    [Ralph] I'm learnding!

[mcp] tavily/tavily_search: {"query": "Claude AI news"...}
[mcp-result] {"results": [...]}