Author: Kimal Honour Djam
An advanced, Anthropic-aligned autonomous development system that transforms Claude Code into a relentless, self-correcting development agent. Built on the original "Ralph Wiggum" pattern by Geoffrey Huntley, enhanced with best practices from Anthropic's engineering team.
Ralph Ultra enables fully autonomous, error-free, production-level app development for both new projects and fixing incomplete ones. It operates on a simple philosophy:
Plan → Implement → Verify → Learn → Repeat
✨ 21 Modular Skills - Deep codebase navigation, flaky test detection, security auditing, and more 🔒 Three-Tier Security Model - Sandbox, Standard, and YOLO modes for safe autonomous operation 🔄 Smart Self-Correction Loop - Autonomously debugs and fixes errors until all verification gates pass 📊 Real-Time Observability - Web dashboard and CLI status for progress tracking 🎯 Skill-Based Extension - Modular architecture for handling complex edge cases 🔌 Claude Code Plugin - Seamless IDE integration via MCP
- Quick Start
- The Methodology
- Installation
- Usage
- Skills Reference
- Security Model
- Configuration
- Architecture
- Documentation
- Contributing
- License
# Install Ralph Ultra
git clone https://github.com/kimhons/ralph-ultra-claude-code.git
cd ralph-ultra-claude-code
sudo ./install.sh
# Initialize a new project
ralph init my-nextjs-app --template nextjs
# Configure your blueprint
cd my-nextjs-app
# Edit CLAUDE.md and prd.json with your requirements
# Run the autonomous development loop
ralph run# Navigate to your project
cd /path/to/your/project
# Add Ralph Ultra and analyze the codebase
ralph fix --analyze
# Configure CLAUDE.md and prd.json based on the analysis
# Start the autonomous loop
ralph run# In Claude Code, install the plugin:
/plugin marketplace add kimhons/ralph-ultra-claude-code
# Then use Ralph commands directly in Claude Code:
/ralph init my-project --template python
/ralph run
/ralph statusRalph Ultra operates in three distinct phases, moving from human-led architectural decisions to fully autonomous AI-driven development.
You define the blueprint:
-
CLAUDE.md - The "brain" of your project:
- Architecture patterns
- Coding standards
- Commands to run
- Technology stack
- Security requirements
-
prd.json - The "task list":
- User stories with clear acceptance criteria
- Dependencies between stories
- Priority and complexity estimates
The AI agent enters a continuous loop:
┌─────────────────────────────────────────┐
│ 1. Context Gathering │
│ - Read CLAUDE.md, prd.json │
│ - Load codebase index │
│ - Review progress.txt │
└────────────┬────────────────────────────┘
▼
┌─────────────────────────────────────────┐
│ 2. Planning │
│ - Select next user story │
│ - Break into micro-tasks │
│ - Identify dependencies │
└────────────┬────────────────────────────┘
▼
┌─────────────────────────────────────────┐
│ 3. Implementation │
│ - Write/modify code │
│ - Update tests │
│ - Document changes │
└────────────┬────────────────────────────┘
▼
┌─────────────────────────────────────────┐
│ 4. Verification (5 Gates) │
│ ✓ Static Analysis (linter) │
│ ✓ Type Checking │
│ ✓ Automated Tests │
│ ✓ Security Audit │
│ ✓ Visual Verification (UI only) │
└────────────┬────────────────────────────┘
│
┌────────┴────────┐
│ All Pass? │
└────────┬────────┘
Yes│ No
│ │
│ ▼
│ ┌──────────────────────────┐
│ │ Self-Correction Loop │
│ │ 1. Analyze error │
│ │ 2. Diagnose root cause │
│ │ 3. Formulate fix │
│ │ 4. Implement fix │
│ │ 5. Re-verify from Gate 1│
│ └──────────┬───────────────┘
│ │
│ ┌─────────┴──────────┐
│ │ Fixed? (Max 3x) │
│ └─────────┬──────────┘
│ Yes│ No
│ │ │
│ │ ▼
│ │ [Escalate: Revert,
│ │ Mark Blocked,
│ │ Move to Next Story]
│ │
▼ ▼
┌─────────────────────────────────────────┐
│ 5. Commit & Progress Update │
│ - Git commit with detailed message │
│ - Update prd.json (story status) │
│ - Append to progress.txt │
└────────────┬────────────────────────────┘
│
┌────────┴────────┐
│ More Stories? │
└────────┬────────┘
Yes│ No
│ │
│ ▼
│ [Phase 3: Completion]
│
└─────► [Loop Again]
The loop continues until all stories in prd.json are marked "done", then the agent signals completion.
For non-technical users, copy and paste this into Claude Code:
Please install Ralph Ultra for me. Here is the repository:
https://github.com/kimhons/ralph-ultra-claude-code
Clone it, run the installer, and confirm when it's ready.
Claude Code will handle the entire installation.
# Clone the repository
git clone https://github.com/kimhons/ralph-ultra-claude-code.git
# Navigate to the directory
cd ralph-ultra-claude-code
# Run the installer (requires sudo for global installation)
sudo ./install.shralph --version
# Output: Ralph Ultra v1.0.0
ralph --help
# Shows all available commandscd ralph-ultra-claude-code
sudo ./uninstall.sh| Command | Description | Example |
|---|---|---|
ralph init <name> [--template <type>] |
Initialize a new project | ralph init my-app --template nextjs |
ralph fix [--analyze] |
Add Ralph to existing project | ralph fix --analyze |
ralph run [n] |
Run the loop for n iterations (default 20) | ralph run 50 |
ralph status |
Show current PRD status and progress | ralph status |
ralph prd |
Interactive PRD wizard | ralph prd |
ralph verify [--gate N] |
Run verification gates | ralph verify --gate 3 |
ralph deploy --env <env> |
Deploy with safety checks | ralph deploy --env production |
ralph dashboard |
Launch web UI | ralph dashboard |
ralph skill <action> |
Manage skills | ralph skill list |
ralph security-audit |
Run security scan | ralph security-audit |
Available templates for ralph init:
- nextjs - Next.js 14+ with App Router, TypeScript, Tailwind CSS
- python - Python 3.11+ with FastAPI, Pytest, Ruff
- node - Node.js 20+ with Express, Jest, ESLint
- flutter - Flutter 3.x mobile app with Riverpod
- default - Generic template for any stack
# Sandbox mode (default, read-only)
ralph run
# Standard mode (allowlist-based)
ralph run --security standard
# YOLO mode (full permissions, requires confirmation)
ralph run --security yoloSee Security Model for details.
Ralph Ultra includes 21 built-in skills for handling complex development scenarios:
| Skill | Purpose | When to Use |
|---|---|---|
| deep-codebase-navigator | Semantic indexing for large codebases | 50+ files or context overflow |
| flaky-test-detector | Identify non-deterministic tests | Intermittent test failures |
| mcp-tool-manager | Switch between live/mocked APIs | Testing without network |
| requirement-analyzer | Find ambiguous requirements | Before starting features |
| environment-doctor | Ensure healthy dev environment | New machines or after updates |
| git-conflict-resolver | Autonomous conflict resolution | Merging feature branches |
| performance-guardian | Performance regression detection | Before merging optimizations |
| security-auditor | Vulnerability scanning | Before every commit |
| schema-migration-governor | Safe database migrations | Schema changes |
| multi-service-orchestrator | Coordinate microservices | Monorepo or distributed systems |
| Skill | Command | Purpose |
|---|---|---|
| ralph-init | ralph init |
Initialize new projects |
| ralph-fix | ralph fix |
Add Ralph to existing projects |
| ralph-run | ralph run |
Execute the autonomous loop |
| ralph-status | ralph status |
Show progress and PRD status |
| ralph-prd | ralph prd |
Interactive PRD wizard |
| ralph-verify | ralph verify |
Manual verification gates |
| ralph-deploy | ralph deploy |
Safe deployments |
| ralph-dashboard | ralph dashboard |
Web UI for monitoring |
| ralph-security-audit | ralph security-audit |
Comprehensive security scan |
| ralph-skill | ralph skill |
Manage custom skills |
# Analyze requirements for ambiguity
ralph skill run requirement-analyzer
# Detect flaky tests with 10 runs
ralph skill run flaky-test-detector --runs 10
# Create a semantic codebase index
ralph skill run deep-codebase-navigator
# List all available skills
ralph skill listSee docs/SKILLS.md for complete documentation.
Ralph Ultra implements a three-tier security model to balance autonomy with safety:
Philosophy: "Read everything, write nothing without permission."
- ✅ Read files, directories
- ✅ Run analysis commands (grep, find, ls)
- ✅ Git read operations (status, log, diff)
- ❌ File writes (requires approval)
- ❌ Package installations
- ❌ Git commits/pushes
- ❌ Network operations
Use Case: Initial exploration, untrusted code.
Philosophy: "Allow common safe operations, block dangerous ones."
- ✅ Allowlist-based regex patterns
- ✅ Common dev commands (npm install, git commit, pytest)
- ❌ Destructive operations (git reset --hard, rm -rf /)
- ❌ System-level changes (sudo, chmod 777)
Use Case: Most development work.
Example Configuration (.ralph/config.json):
{
"security": {
"mode": "standard",
"allowlist": [
"^npm (install|test|run build)$",
"^git (add|commit|status|push)$",
"^pytest",
"^docker-compose up -d$"
]
}
}Philosophy: "Maximum velocity, minimum friction."
- ✅ Everything - Full system permissions
⚠️ Requires interactive confirmation:ralph run --security yolo⚠️ All commands logged to.ralph/audit.log⚠️ Git commits before destructive operations
Use Case: Rapid prototyping, trusted private projects.
See docs/SECURITY.md for complete documentation.
{
"security": {
"mode": "standard",
"allowlist": [
"^npm (install|test|run build)$",
"^git (add|commit|status)$"
],
"blocklist": [
"^rm -rf /$",
"^sudo"
],
"require_approval": [
"^git push",
"^npm publish"
]
},
"verification": {
"skip_gates": [],
"custom_gates": []
},
"skills": {
"enabled": ["deep-codebase-navigator", "security-auditor"],
"disabled": []
}
}# Project: my-nextjs-app
## Commands
- **Install**: `npm install`
- **Dev**: `npm run dev`
- **Test**: `npm test`
- **Lint**: `npm run lint`
- **Build**: `npm run build`
## Code Style
- Framework: Next.js 14 (App Router)
- Language: TypeScript 5.3 (strict mode)
- Styling: Tailwind CSS
- State: Zustand
## Architecture
- `/app`: Pages and layouts
- `/components`: React components
- `/lib`: Utilities and hooks
- `/app/api`: API routes
## Verification Workflow
1. `npm run lint` must pass
2. `npm run typecheck` must pass
3. `npm test` must pass
4. Visual verification for UI changes{
"project": "my-nextjs-app",
"version": "1.0.0",
"description": "E-commerce storefront with Stripe integration",
"stories": [
{
"id": "US-001",
"title": "Add product listing page",
"description": "As a user, I want to view all available products",
"status": "pending",
"priority": "high",
"acceptance_criteria": [
"Products are fetched from /api/products",
"Each product shows: image, name, price, description",
"Products are displayed in a responsive grid",
"Loading state is shown while fetching",
"Error state is shown if fetch fails"
],
"depends_on": [],
"estimated_complexity": "simple"
}
]
}Validate your PRD against the schema:
ralph prd validate┌───────────────────────────────────────────────────────────────┐
│ Ralph Ultra CLI │
│ Commands: init, fix, run, status, verify, deploy, etc. │
└────────────────────────┬──────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────┐
│ Loop Engine (Core) │
│ - Context gathering │
│ - Story selection & planning │
│ - Code generation & modification │
│ - Verification orchestration │
│ - Self-correction & error recovery │
└────────────────────────┬──────────────────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
┌────────────────┐ ┌────────────┐ ┌────────────────┐
│ Security Layer │ │ Skills │ │ Verification │
│ - Sandbox │ │ 21 Modules │ │ 5 Gates │
│ - Standard │ │ │ │ │
│ - YOLO │ │ │ │ 1. Lint │
└────────────────┘ └────────────┘ │ 2. Types │
│ 3. Tests │
│ 4. Security │
│ 5. Visual │
└────────────────┘
│ │ │
└───────────────┼───────────────┘
│
▼
┌───────────────────────────────────────────────────────────────┐
│ Project State │
│ - CLAUDE.md (blueprint) │
│ - prd.json (stories & status) │
│ - progress.txt (agent memory) │
│ - config.json (security & preferences) │
│ - audit.log (command history) │
└───────────────────────────────────────────────────────────────┘
All code must pass through 5 non-negotiable gates before being committed:
| Gate | Purpose | Tool | Pass Criteria |
|---|---|---|---|
| 1. Static Analysis | Catch syntax errors, style violations | ESLint, Ruff | Zero errors |
| 2. Type Checking | Ensure type safety | TypeScript, MyPy | Zero errors |
| 3. Automated Tests | Verify logical correctness | Jest, Pytest | All tests pass |
| 4. Security Audit | Identify vulnerabilities | npm audit, safety | No HIGH/CRITICAL |
| 5. Visual Verification | Confirm UI changes | Browser skill | Matches acceptance criteria |
When any gate fails, the agent enters an autonomous debugging loop:
- Analyze the Error - Read error message, stack trace, file/line number
- Diagnose Root Cause - Formulate a hypothesis
- Formulate Micro-Plan - Create a small, targeted fix
- Implement Fix - Make the code changes
- Re-verify from Gate 1 - Run ALL gates again
Circuit Breaker: After 3 failed attempts on the same error, the agent:
- Reverts the code changes
- Marks the story as "blocked"
- Moves to the next story
- Logs the issue for human review
| Document | Description |
|---|---|
| SECURITY.md | Complete security model documentation |
| SKILLS.md | All 21 skills with examples and API |
| MIGRATION.md | Migration guide from Enhanced Ralph |
| verification_and_self_correction.md | Deep dive into verification gates |
| infinite_loop_prevention.md | Circuit breaker mechanism |
| edge_cases_and_skills_roadmap.md | Edge case analysis and skill designs |
| ULTIMATE_CLAUDE_CODE_CONFIG_GUIDE.md | Claude Code configuration best practices |
Contributions are welcome! Here's how you can help:
- Check existing issues
- Create a new issue with:
- OS and version
- Ralph Ultra version (
ralph --version) - Project type (Next.js, Python, etc.)
- Full error logs
- Steps to reproduce
# Generate skill scaffold
ralph skill create my-custom-skill
# Implement your skill logic in:
# - skills/my-custom-skill/bin/run.sh
# - skills/my-custom-skill/prompts/main.md
# Validate and test
ralph skill validate my-custom-skill
ralph skill run my-custom-skill --arg key=value
# Submit a PR to the skill marketplace- Fork the repository
- Create a feature branch:
git checkout -b feature/my-new-feature - Make your changes
- Run tests:
./verify_cli.sh - Commit:
git commit -m "Add my new feature" - Push:
git push origin feature/my-new-feature - Open a Pull Request
MIT License - see LICENSE for details.
- Geoffrey Huntley for the original Ralph Wiggum pattern
- Anthropic for Claude Code and their engineering best practices
- The snarktank/ralph community for their contributions
- All contributors and early adopters of Ralph Ultra
If you find Ralph Ultra useful, please consider starring the repository!
- GitHub Issues: https://github.com/kimhons/ralph-ultra-claude-code/issues
- Discord: https://discord.gg/ralph-ultra
- Email: support@ralph-ultra.dev
Built with ❤️ by Kimal Honour Djam
Transforming AI-assisted development, one autonomous loop at a time.