8me

Multi-tiered "Ralph Wiggum" autonomous loop solution with MCP integration

Overview

8me provides tools for implementing autonomous software engineering through persistent, recursive execution loops. Based on the "Ralph Wiggum" methodology (popularized by Geoffrey Huntley), it embraces iterative success over one-shot perfection.

For the AI nerds: This simple loop-until-done pattern was the common approach before sophisticated gating mechanisms, multi-agent orchestration frameworks, and the explosion of agentic tooling. Sometimes the old ways persist because they work.

Core Concept

┌──────────────────────────────────────────────────────────────┐
│                     The Ralph Loop                            │
├──────────────────────────────────────────────────────────────┤
│                                                               │
│    ┌─────────┐      ┌─────────┐      ┌─────────┐            │
│    │  READ   │─────▶│ EXECUTE │─────▶│ VERIFY  │            │
│    │  Task   │      │  Task   │      │ Success │            │
│    └─────────┘      └─────────┘      └────┬────┘            │
│         ▲                                  │                 │
│         │                    ┌─────────────┴─────────────┐  │
│         │                    │                           │  │
│         │              FAIL ▼                     PASS ▼ │  │
│         │           ┌─────────┐                ┌─────────┐  │
│         └───────────│  RETRY  │                │  DONE   │  │
│                     └─────────┘                └─────────┘  │
│                                                               │
└──────────────────────────────────────────────────────────────┘

Success = Imperfect AI × Persistent Loop × External Verification

Deliverables

Each tier is a standalone product that works independently:

Tier	Component	Status	Description
0	tier0-hello-world	✅ Complete	Single-file educational demo (~90 lines)
1	tier1-ralph-loop	✅ Complete	Full Python CLI with verification & retry
2	tier2-ralph-skill	✅ Complete	Claude Code skill integration
3	tier3-mcp-server	✅ Complete	MCP Server (Python + TypeScript)
4	tier4-orchestrator-client	✅ Complete	Pluggable orchestrator with circuit breaker

Quick Start

Tier 0 - Hello World (Simplest)

cd src/tier0-hello-world
pip install anthropic
export ANTHROPIC_API_KEY="sk-ant-..."
python ralph_hello_world.py

Tier 1 - Full Loop

cd src/tier1-ralph-loop
source ../../.venv/bin/activate
python ralph_loop.py --add "Write a haiku about loops"
python ralph_loop.py

Tier 2 - Claude Code Skill

# Copy to Claude Code skills directory
cp -r src/tier2-ralph-skill ~/.claude/skills/ralph-loop

# Then in Claude Code:
/ralph add Write unit tests for auth module
/ralph

Project Structure

8me/
├── src/
│   ├── tier0-hello-world/     # ✅ Simplest loop (~90 lines)
│   │   ├── ralph_hello_world.py
│   │   ├── tasks.txt
│   │   └── README.md
│   ├── tier1-ralph-loop/      # ✅ Full loop with verification
│   │   ├── ralph_loop.py
│   │   ├── task_manager.py
│   │   ├── claude_tools.py
│   │   ├── circuit_breaker.py
│   │   └── README.md
│   ├── tier2-ralph-skill/     # ✅ Claude Code skill
│   │   ├── SKILL.md
│   │   ├── references/
│   │   └── README.md
│   ├── tier3-mcp-server/      # ✅ MCP Server (Python)
│   │   ├── server.py
│   │   ├── pyproject.toml
│   │   └── README.md
│   ├── tier3-mcp-server-ts/   # ✅ MCP Server (TypeScript)
│   │   ├── src/
│   │   ├── package.json
│   │   └── README.md
│   └── tier4-orchestrator-client/  # ✅ Orchestrator
│       ├── orchestrator.py
│       └── README.md
├── docs/                       # Architecture documentation
├── LICENSE
├── CONTRIBUTING.md
└── README.md

Documentation

• Each tier has its own README with full documentation
• Learning resources: 8me Showcase - Tutorials, concepts, and 15 hands-on labs
• Architecture diagrams: docs/architecture-diagrams.md

Note: The showcase labs contain pedagogical variations of the code here. Lab examples may use richer abstractions (interfaces, hooks, builders) optimized for teaching concepts layer-by-layer, while this repo contains the "mundane" working implementations optimized for actual use.

References

• Model Context Protocol
• FastMCP
• Claude Code

License

MIT License - See LICENSE file for details.

---

Part of the Adaptivearts.ai™ research initiative