🔥 Ralph Inferno

February 3, 2026 · View on GitHub

⚠️ DEPRECATED: This project has been superseded by Symbiont. Development has moved there as of February 2026.

🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥
🔥                                              🔥
🔥  ██████╗  █████╗ ██╗     ██████╗ ██╗  ██╗    🔥
🔥  ██╔══██╗██╔══██╗██║     ██╔══██╗██║  ██║    🔥
🔥  ██████╔╝███████║██║     ██████╔╝███████║    🔥
🔥  ██╔══██╗██╔══██║██║     ██╔═══╝ ██╔══██║    🔥
🔥  ██║  ██║██║  ██║███████╗██║     ██║  ██║    🔥
🔥  ╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝     ╚═╝  ╚═╝    🔥
🔥                                              🔥
🔥          I N F E R N O   M O D E             🔥
🔥                                              🔥
🔥  Build while you sleep. Wake to working code 🔥
🔥                   🌙 → ☀️                     🔥
🔥                                              🔥
🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥

Light the fire. Walk away.

Ralph runs autonomously on a VM while you do literally anything else. Come back when it's done. Or don't. Ralph doesn't care.

AI-driven autonomous development workflow.

How It Works

Ralph installs as Claude Code commands and Codex CLI prompts. When you run npx ralph-inferno install, it creates a .ralph/ folder with scripts, syncs .claude/commands/ for Claude Code, and syncs ~/.codex/prompts/ for Codex CLI.

Local Machine                               VM (Sandbox)
┌──────────────────────────┐              ┌─────────────────┐
│ Claude Code or Codex CLI │              │ Agent CLI       │
│ + Ralph commands/prompts │     GitHub   │ + ralph.sh      │
│                          │ ───────────► │                 │
│ /ralph:* or /prompts:*   │              │ Runs specs      │
└──────────────────────────┘              └─────────────────┘

The flow:

You work locally with Claude Code (/ralph:*) or Codex CLI (/prompts:ralph-*)
Deploy pushes your specs to GitHub and starts Ralph on the VM
Ralph runs autonomously on the VM while you sleep
Next day: review what was built

Requirements

Local Machine

Tool	Required	How to install
Node.js	Yes	`brew install node`
Claude Code	Yes (choose one)	`npm install -g @anthropic-ai/claude-code`
Codex CLI	Yes (choose one)	`npm install -g @openai/codex`
GitHub CLI	Recommended	`brew install gh` then `gh auth login`

VM (Sandbox)

Tool	Required	Notes
SSH access	Yes	You need to be able to SSH into the VM
Git	Yes	Usually pre-installed
Claude Code	Yes (choose one)	`npm install -g @anthropic-ai/claude-code`
Claude auth	Yes (if using Claude)	See Authentication below
Codex CLI	Yes (choose one)	`npm install -g @openai/codex`
Codex auth	Yes (if using Codex)	Run `codex login` OR set `OPENAI_API_KEY`
GitHub CLI	Yes	`brew install gh` then `gh auth login`

Important: Both machines need gh auth login for Git operations to work!

Optional

Codex web search - Run Codex with --search (or enable it in Codex config) for /prompts:ralph-discover.
Claude Chrome Extension - Lets Claude browse websites during /ralph:discover.
If browsing isn’t available, use the dev-browser skill as a fallback.
Cloud CLI (hcloud, gcloud, doctl, aws) - For VM management
ntfy.sh - Push notifications when Ralph finishes

Installation

Step 1: Install Ralph locally

cd your-project
npx ralph-inferno install

This creates:

.ralph/ - Scripts and config
.claude/commands/ - Claude Code commands
~/.codex/prompts/ - Codex prompt files

Step 2: Set up your VM

SSH into your VM and install the prerequisites:

# Install Node.js (if not installed)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install Claude Code (if using Claude)
npm install -g @anthropic-ai/claude-code

# Install Codex CLI (if using Codex)
npm install -g @openai/codex

# Authenticate Claude - see Authentication section below
claude login                    # Simplest option for Pro/Max subscribers

# Authenticate Codex (if using Codex):
codex login                      # If you prefer browser-based login
# OR
export OPENAI_API_KEY="sk-..."   # If using API key

# Install and authenticate GitHub CLI
sudo apt-get install gh
gh auth login

# Install Playwright dependencies (for E2E tests)
npx playwright install-deps
npx playwright install

Step 3: Verify setup

On your local machine, start your CLI:

Claude Code:

claude

Then run:

/ralph:discover
/ralph:plan
/ralph:deploy

Codex CLI:

codex

Then run:

/prompts:ralph-discover
/prompts:ralph-plan
/prompts:ralph-deploy

Authentication

Claude Code supports multiple authentication methods. Set these on your VM (not local machine):

Option 1: Claude Subscription (Simplest)

claude login

Option 2: Anthropic API Key

export ANTHROPIC_API_KEY="sk-ant-..."

Option 3: AWS Bedrock

export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_MODEL="us.anthropic.claude-sonnet-4-20250514-v1:0"
export AWS_REGION="us-east-1"
export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."

Option 4: Azure AI Foundry

export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_BASE_URL="https://your-resource.services.ai.azure.com/api/v1"
export ANTHROPIC_FOUNDRY_API_KEY="..."
export ANTHROPIC_FOUNDRY_RESOURCE="your-resource-name"

Tip: Add these to ~/.bashrc on your VM so they persist across sessions.

Update

Update core files while preserving your config:

npx ralph-inferno update

Or use the command/prompt:

/ralph:update            # Claude Code
/prompts:ralph-update    # Codex CLI

Workflow

Ralph supports two entry points: Greenfield (new apps) and Brownfield (existing apps).

┌─────────────────────────────────────────────────────────────────────────────┐
│                        TWO ENTRY POINTS                                      │
└─────────────────────────────────────────────────────────────────────────────┘

   GREENFIELD (new app)                    BROWNFIELD (existing app)
         │                                          │
         ▼                                          ▼
   /ralph:idea ──────────────────────────► /ralph:change-request
   (BMAD Brainstorm)                       (Analyze scope: S/M/L)
         │                                          │
         ▼                                          │
   PROJECT-BRIEF.md                                 │
         │                                          │
         ▼                                          │
   /ralph:discover                                  │
   (BMAD Analyst)                                   │
         │                                          │
         ▼                                          ▼
      PRD.md ─────────────────────────► CHANGE-REQUEST.md
                            │
                            ▼
                      /ralph:plan
                      (auto-detects input)
                            │
                            ▼
                      /ralph:deploy → VM → /ralph:review

Codex CLI equivalents use /prompts:ralph-* (see table below).


### Commands / Prompts
| Claude Code | Codex CLI | Description |
|-------------|-----------|-------------|
| `/ralph:idea` | `/prompts:ralph-idea` | **Greenfield start** - BMAD brainstorm → PROJECT-BRIEF.md |
| `/ralph:discover` | `/prompts:ralph-discover` | BMAD analyst mode → PRD.md |
| `/ralph:change-request` | `/prompts:ralph-change-request` | **Brownfield start** - Analyze changes → CR specs |
| `/ralph:plan` | `/prompts:ralph-plan` | Creates specs from PRD or Change Request |
| `/ralph:preflight` | `/prompts:ralph-preflight` | Verify requirements before deployment |
| `/ralph:deploy` | `/prompts:ralph-deploy` | Push to GitHub, choose mode, start Ralph on VM |
| `/ralph:review` | `/prompts:ralph-review` | Open SSH tunnels, test the app |
| `/ralph:status` | `/prompts:ralph-status` | Check Ralph's progress on VM |
| `/ralph:abort` | `/prompts:ralph-abort` | Stop Ralph on VM |
| `/ralph:update` | `/prompts:ralph-update` | Update Ralph to latest version |

### Deploy Modes

When running deploy (`/ralph:deploy` or `/prompts:ralph-deploy`), you choose a mode:

| Mode | What it does |
|------|--------------|
| **Quick** | Spec execution + build verify only |
| **Standard** | + Playwright E2E tests + auto-CR generation |
| **Inferno** | + Design review + parallel worktrees |

### Tips for Best Results

**Discovery mode works best when the agent can browse the web.**

- Codex CLI: use web search (`--search` or enable it in config)
- Claude Code: use the Claude Chrome Extension
- Otherwise: use the `dev-browser` skill as a fallback

### Example: New App (Greenfield)

```bash
# 1. Install Ralph
npx ralph-inferno install

# 2. Brainstorm & Discover
/ralph:idea "todo app"      # BMAD brainstorm → PROJECT-BRIEF.md
/ralph:discover             # BMAD analyst → PRD.md

# 3. Plan & Deploy
/ralph:plan                 # Generate specs
/ralph:deploy               # Send to VM

# 4. Review
/ralph:review               # Test what Ralph built

# Codex CLI equivalents
/prompts:ralph-idea "todo app"
/prompts:ralph-discover
/prompts:ralph-plan
/prompts:ralph-deploy
/prompts:ralph-review

Example: Existing App (Brownfield)

# 1. Describe changes
/ralph:change-request "add dark mode"   # Analyze scope → CR specs

# 2. Plan & Deploy
/ralph:plan                 # Auto-detects Change Request
/ralph:deploy               # Send to VM

# 3. Review
/ralph:review               # Test the changes

# Codex CLI equivalents
/prompts:ralph-change-request "add dark mode"
/prompts:ralph-plan
/prompts:ralph-deploy
/prompts:ralph-review

Language Agnostic

Ralph auto-detects your project type and uses the appropriate build/test commands:

Project Type	Build Command	Test Command
Node.js (package.json)	`npm run build`	`npm test`
Rust (Cargo.toml)	`cargo build`	`cargo test`
Go (go.mod)	`go build ./...`	`go test ./...`
Python (pyproject.toml)	`python -m build`	`pytest`
Makefile	`make build`	`make test`

Custom commands: Override in .ralph/config.json:

{
  "build_cmd": "yarn build",
  "test_cmd": "yarn test:ci"
}

Set agent to claude or codex (or auto to use whatever is installed on the VM).

Safety

Ralph runs AI-generated code autonomously. For safety:

ALWAYS run on a disposable VM - never on your local machine
Review generated code before production
Never store credentials in code

Cloud Providers

Ralph supports multiple cloud providers for VM execution:

Provider	CLI	Notes
Hetzner	`hcloud`	Cheapest, great for Europe
Google Cloud	`gcloud`	Good free tier
DigitalOcean	`doctl`	Simple and reliable
AWS	`aws`	Enterprise option
SSH	-	Use your own server

Config File

Configuration is stored in .ralph/config.json:

{
  "version": "1.0.9",
  "language": "en",
  "provider": "hcloud",
  "vm_name": "ralph-sandbox",
  "region": "fsn1",
  "github": {
    "username": "your-username"
  },
  "agent": "claude",
  "claude": {
    "auth_method": "subscription"
  },
  "codex": {
    "auth_method": "account"
  },
  "notifications": {
    "ntfy_enabled": true,
    "ntfy_topic": "my-unique-ralph-topic"
  },
  "build_cmd": "npm run build",
  "test_cmd": "npm test"
}

Auth method options:

Value	Description
`subscription`	Uses `claude login` (Pro/Max subscription)
`api_key`	Uses `ANTHROPIC_API_KEY` env var
`bedrock`	Uses AWS Bedrock env vars
`foundry`	Uses Azure AI Foundry env vars

Documentation

Architecture - System overview and memory model
CLI Flags - All ralph.sh options
Token Optimization - Cost-saving strategies

Credits & Inspiration

Ralph Inferno builds on ideas from:

snarktank/ralph - Ryan Carson's original Ralph concept
BMAD Method - The discovery workflow (/ralph:idea and /ralph:discover) is heavily inspired by BMAD's Brainstorm and Analyst personas
how-to-build-a-coding-agent - Geoffrey Huntley's agent patterns
claude-ralph - Robin Oppenstam's implementation

License

MIT