{"id":40765674,"url":"https://github.com/sandstream/ralph-inferno","last_synced_at":"2026-01-30T20:00:40.358Z","repository":{"id":332659181,"uuid":"1134531641","full_name":"sandstream/ralph-inferno","owner":"sandstream","description":"AI-driven autonomous development workflow - Ralph builds while you sleep","archived":false,"fork":false,"pushed_at":"2026-01-30T12:42:08.000Z","size":296,"stargazers_count":197,"open_issues_count":1,"forks_count":19,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-30T16:03:10.944Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sandstream.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-14T21:06:14.000Z","updated_at":"2026-01-30T12:42:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"d1019e34-3d80-4cc0-9cb5-72c020f81be1","html_url":"https://github.com/sandstream/ralph-inferno","commit_stats":null,"previous_names":["sandstream/ralph-inferno"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sandstream/ralph-inferno","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandstream%2Fralph-inferno","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandstream%2Fralph-inferno/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandstream%2Fralph-inferno/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandstream%2Fralph-inferno/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sandstream","download_url":"https://codeload.github.com/sandstream/ralph-inferno/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandstream%2Fralph-inferno/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28918235,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-30T19:10:10.838Z","status":"ssl_error","status_checked_at":"2026-01-30T19:06:40.573Z","response_time":66,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-21T18:00:26.196Z","updated_at":"2026-01-30T20:00:40.348Z","avatar_url":"https://github.com/sandstream.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# 🔥 Ralph Inferno\n\n```\n🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥\n🔥                                              🔥\n🔥  ██████╗  █████╗ ██╗     ██████╗ ██╗  ██╗    🔥\n🔥  ██╔══██╗██╔══██╗██║     ██╔══██╗██║  ██║    🔥\n🔥  ██████╔╝███████║██║     ██████╔╝███████║    🔥\n🔥  ██╔══██╗██╔══██║██║     ██╔═══╝ ██╔══██║    🔥\n🔥  ██║  ██║██║  ██║███████╗██║     ██║  ██║    🔥\n🔥  ╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝     ╚═╝  ╚═╝    🔥\n🔥                                              🔥\n🔥          I N F E R N O   M O D E             🔥\n🔥                                              🔥\n🔥  Build while you sleep. Wake to working code 🔥\n🔥                   🌙 → ☀️                     🔥\n🔥                                              🔥\n🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥🔥\n```\n\n\u003e **Light the fire. Walk away.**\n\u003e\n\u003e Ralph runs autonomously on a VM while you do literally anything else.\n\u003e Come back when it's done. Or don't. Ralph doesn't care.\n\nAI-driven autonomous development workflow.\n\n## How It Works\n\nRalph 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.\n\n```\nLocal Machine                               VM (Sandbox)\n┌──────────────────────────┐              ┌─────────────────┐\n│ Claude Code or Codex CLI │              │ Agent CLI       │\n│ + Ralph commands/prompts │     GitHub   │ + ralph.sh      │\n│                          │ ───────────► │                 │\n│ /ralph:* or /prompts:*   │              │ Runs specs      │\n└──────────────────────────┘              └─────────────────┘\n```\n\n**The flow:**\n1. You work locally with Claude Code (`/ralph:*`) or Codex CLI (`/prompts:ralph-*`)\n2. Deploy pushes your specs to GitHub and starts Ralph on the VM\n3. Ralph runs autonomously on the VM while you sleep\n4. Next day: review what was built\n\n## Requirements\n\n### Local Machine\n\n| Tool | Required | How to install |\n|------|----------|----------------|\n| Node.js | Yes | `brew install node` |\n| Claude Code | Yes (choose one) | `npm install -g @anthropic-ai/claude-code` |\n| Codex CLI | Yes (choose one) | `npm install -g @openai/codex` |\n| GitHub CLI | Recommended | `brew install gh` then `gh auth login` |\n\n### VM (Sandbox)\n\n| Tool | Required | Notes |\n|------|----------|-------|\n| SSH access | Yes | You need to be able to SSH into the VM |\n| Git | Yes | Usually pre-installed |\n| Claude Code | Yes (choose one) | `npm install -g @anthropic-ai/claude-code` |\n| Claude auth | Yes (if using Claude) | See [Authentication](#authentication) below |\n| Codex CLI | Yes (choose one) | `npm install -g @openai/codex` |\n| Codex auth | Yes (if using Codex) | Run `codex login` OR set `OPENAI_API_KEY` |\n| GitHub CLI | Yes | `brew install gh` then `gh auth login` |\n\n**Important:** Both machines need `gh auth login` for Git operations to work!\n\n### Optional\n\n- **Codex web search** - Run Codex with `--search` (or enable it in Codex config) for `/prompts:ralph-discover`.\n- **Claude Chrome Extension** - Lets Claude browse websites during `/ralph:discover`.\n- If browsing isn’t available, use the `dev-browser` skill as a fallback.\n- Cloud CLI (`hcloud`, `gcloud`, `doctl`, `aws`) - For VM management\n- [ntfy.sh](https://ntfy.sh) - Push notifications when Ralph finishes\n\n## Installation\n\n### Step 1: Install Ralph locally\n\n```bash\ncd your-project\nnpx ralph-inferno install\n```\n\nThis creates:\n- `.ralph/` - Scripts and config\n- `.claude/commands/` - Claude Code commands\n- `~/.codex/prompts/` - Codex prompt files\n\n### Step 2: Set up your VM\n\nSSH into your VM and install the prerequisites:\n\n```bash\n# Install Node.js (if not installed)\ncurl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -\nsudo apt-get install -y nodejs\n\n# Install Claude Code (if using Claude)\nnpm install -g @anthropic-ai/claude-code\n\n# Install Codex CLI (if using Codex)\nnpm install -g @openai/codex\n\n# Authenticate Claude - see Authentication section below\nclaude login                    # Simplest option for Pro/Max subscribers\n\n# Authenticate Codex (if using Codex):\ncodex login                      # If you prefer browser-based login\n# OR\nexport OPENAI_API_KEY=\"sk-...\"   # If using API key\n\n# Install and authenticate GitHub CLI\nsudo apt-get install gh\ngh auth login\n\n# Install Playwright dependencies (for E2E tests)\nnpx playwright install-deps\nnpx playwright install\n```\n\n### Step 3: Verify setup\n\nOn your local machine, start your CLI:\n\nClaude Code:\n```bash\nclaude\n```\nThen run:\n- `/ralph:discover`\n- `/ralph:plan`\n- `/ralph:deploy`\n\nCodex CLI:\n```bash\ncodex\n```\nThen run:\n- `/prompts:ralph-discover`\n- `/prompts:ralph-plan`\n- `/prompts:ralph-deploy`\n\n## Authentication\n\nClaude Code supports multiple authentication methods. Set these on your **VM** (not local machine):\n\n### Option 1: Claude Subscription (Simplest)\n```bash\nclaude login\n```\n\n### Option 2: Anthropic API Key\n```bash\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n```\n\n### Option 3: AWS Bedrock\n```bash\nexport CLAUDE_CODE_USE_BEDROCK=1\nexport ANTHROPIC_MODEL=\"us.anthropic.claude-sonnet-4-20250514-v1:0\"\nexport AWS_REGION=\"us-east-1\"\nexport AWS_ACCESS_KEY_ID=\"...\"\nexport AWS_SECRET_ACCESS_KEY=\"...\"\n```\n\n### Option 4: Azure AI Foundry\n```bash\nexport CLAUDE_CODE_USE_FOUNDRY=1\nexport ANTHROPIC_FOUNDRY_BASE_URL=\"https://your-resource.services.ai.azure.com/api/v1\"\nexport ANTHROPIC_FOUNDRY_API_KEY=\"...\"\nexport ANTHROPIC_FOUNDRY_RESOURCE=\"your-resource-name\"\n```\n\n\u003e **Tip:** Add these to `~/.bashrc` on your VM so they persist across sessions.\n\n## Update\n\nUpdate core files while preserving your config:\n\n```bash\nnpx ralph-inferno update\n```\n\nOr use the command/prompt:\n```\n/ralph:update            # Claude Code\n/prompts:ralph-update    # Codex CLI\n```\n\n## Workflow\n\nRalph supports two entry points: **Greenfield** (new apps) and **Brownfield** (existing apps).\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                        TWO ENTRY POINTS                                      │\n└─────────────────────────────────────────────────────────────────────────────┘\n\n   GREENFIELD (new app)                    BROWNFIELD (existing app)\n         │                                          │\n         ▼                                          ▼\n   /ralph:idea ──────────────────────────► /ralph:change-request\n   (BMAD Brainstorm)                       (Analyze scope: S/M/L)\n         │                                          │\n         ▼                                          │\n   PROJECT-BRIEF.md                                 │\n         │                                          │\n         ▼                                          │\n   /ralph:discover                                  │\n   (BMAD Analyst)                                   │\n         │                                          │\n         ▼                                          ▼\n      PRD.md ─────────────────────────► CHANGE-REQUEST.md\n                            │\n                            ▼\n                      /ralph:plan\n                      (auto-detects input)\n                            │\n                            ▼\n                      /ralph:deploy → VM → /ralph:review\n```\n\nCodex CLI equivalents use `/prompts:ralph-*` (see table below).\n```\n\n### Commands / Prompts\n| Claude Code | Codex CLI | Description |\n|-------------|-----------|-------------|\n| `/ralph:idea` | `/prompts:ralph-idea` | **Greenfield start** - BMAD brainstorm → PROJECT-BRIEF.md |\n| `/ralph:discover` | `/prompts:ralph-discover` | BMAD analyst mode → PRD.md |\n| `/ralph:change-request` | `/prompts:ralph-change-request` | **Brownfield start** - Analyze changes → CR specs |\n| `/ralph:plan` | `/prompts:ralph-plan` | Creates specs from PRD or Change Request |\n| `/ralph:preflight` | `/prompts:ralph-preflight` | Verify requirements before deployment |\n| `/ralph:deploy` | `/prompts:ralph-deploy` | Push to GitHub, choose mode, start Ralph on VM |\n| `/ralph:review` | `/prompts:ralph-review` | Open SSH tunnels, test the app |\n| `/ralph:status` | `/prompts:ralph-status` | Check Ralph's progress on VM |\n| `/ralph:abort` | `/prompts:ralph-abort` | Stop Ralph on VM |\n| `/ralph:update` | `/prompts:ralph-update` | Update Ralph to latest version |\n\n### Deploy Modes\n\nWhen running deploy (`/ralph:deploy` or `/prompts:ralph-deploy`), you choose a mode:\n\n| Mode | What it does |\n|------|--------------|\n| **Quick** | Spec execution + build verify only |\n| **Standard** | + Playwright E2E tests + auto-CR generation |\n| **Inferno** | + Design review + parallel worktrees |\n\n### Tips for Best Results\n\n**Discovery mode works best when the agent can browse the web.**\n\n- Codex CLI: use web search (`--search` or enable it in config)\n- Claude Code: use the Claude Chrome Extension\n- Otherwise: use the `dev-browser` skill as a fallback\n\n### Example: New App (Greenfield)\n\n```bash\n# 1. Install Ralph\nnpx ralph-inferno install\n\n# 2. Brainstorm \u0026 Discover\n/ralph:idea \"todo app\"      # BMAD brainstorm → PROJECT-BRIEF.md\n/ralph:discover             # BMAD analyst → PRD.md\n\n# 3. Plan \u0026 Deploy\n/ralph:plan                 # Generate specs\n/ralph:deploy               # Send to VM\n\n# 4. Review\n/ralph:review               # Test what Ralph built\n\n# Codex CLI equivalents\n/prompts:ralph-idea \"todo app\"\n/prompts:ralph-discover\n/prompts:ralph-plan\n/prompts:ralph-deploy\n/prompts:ralph-review\n```\n\n### Example: Existing App (Brownfield)\n\n```bash\n# 1. Describe changes\n/ralph:change-request \"add dark mode\"   # Analyze scope → CR specs\n\n# 2. Plan \u0026 Deploy\n/ralph:plan                 # Auto-detects Change Request\n/ralph:deploy               # Send to VM\n\n# 3. Review\n/ralph:review               # Test the changes\n\n# Codex CLI equivalents\n/prompts:ralph-change-request \"add dark mode\"\n/prompts:ralph-plan\n/prompts:ralph-deploy\n/prompts:ralph-review\n```\n\n## Language Agnostic\n\nRalph auto-detects your project type and uses the appropriate build/test commands:\n\n| Project Type | Build Command | Test Command |\n|--------------|---------------|--------------|\n| Node.js (package.json) | `npm run build` | `npm test` |\n| Rust (Cargo.toml) | `cargo build` | `cargo test` |\n| Go (go.mod) | `go build ./...` | `go test ./...` |\n| Python (pyproject.toml) | `python -m build` | `pytest` |\n| Makefile | `make build` | `make test` |\n\n**Custom commands:** Override in `.ralph/config.json`:\n```json\n{\n  \"build_cmd\": \"yarn build\",\n  \"test_cmd\": \"yarn test:ci\"\n}\n```\n\nSet `agent` to `claude` or `codex` (or `auto` to use whatever is installed on the VM).\n\n## Safety\n\nRalph runs AI-generated code autonomously. For safety:\n\n- **ALWAYS run on a disposable VM** - never on your local machine\n- Review generated code before production\n- Never store credentials in code\n\n## Cloud Providers\n\nRalph supports multiple cloud providers for VM execution:\n\n| Provider | CLI | Notes |\n|----------|-----|-------|\n| Hetzner | `hcloud` | Cheapest, great for Europe |\n| Google Cloud | `gcloud` | Good free tier |\n| DigitalOcean | `doctl` | Simple and reliable |\n| AWS | `aws` | Enterprise option |\n| SSH | - | Use your own server |\n\n## Config File\n\nConfiguration is stored in `.ralph/config.json`:\n\n```json\n{\n  \"version\": \"1.0.9\",\n  \"language\": \"en\",\n  \"provider\": \"hcloud\",\n  \"vm_name\": \"ralph-sandbox\",\n  \"region\": \"fsn1\",\n  \"github\": {\n    \"username\": \"your-username\"\n  },\n  \"agent\": \"claude\",\n  \"claude\": {\n    \"auth_method\": \"subscription\"\n  },\n  \"codex\": {\n    \"auth_method\": \"account\"\n  },\n  \"notifications\": {\n    \"ntfy_enabled\": true,\n    \"ntfy_topic\": \"my-unique-ralph-topic\"\n  },\n  \"build_cmd\": \"npm run build\",\n  \"test_cmd\": \"npm test\"\n}\n```\n\n**Auth method options:**\n| Value | Description |\n|-------|-------------|\n| `subscription` | Uses `claude login` (Pro/Max subscription) |\n| `api_key` | Uses `ANTHROPIC_API_KEY` env var |\n| `bedrock` | Uses AWS Bedrock env vars |\n| `foundry` | Uses Azure AI Foundry env vars |\n\n## Documentation\n\n- [Architecture](docs/ARCHITECTURE.md) - System overview and memory model\n- [CLI Flags](docs/CLI-FLAGS.md) - All ralph.sh options\n- [Token Optimization](docs/TOKEN-OPTIMIZATION.md) - Cost-saving strategies\n\n## Credits \u0026 Inspiration\n\nRalph Inferno builds on ideas from:\n\n- [snarktank/ralph](https://github.com/snarktank/ralph) - Ryan Carson's original Ralph concept\n- [BMAD Method](https://github.com/bmadcode/BMAD-METHOD) - The discovery workflow (`/ralph:idea` and `/ralph:discover`) is heavily inspired by BMAD's Brainstorm and Analyst personas\n- [how-to-build-a-coding-agent](https://github.com/ghuntley/how-to-build-a-coding-agent) - Geoffrey Huntley's agent patterns\n- [claude-ralph](https://github.com/RobinOppenstam/claude-ralph) - Robin Oppenstam's implementation\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsandstream%2Fralph-inferno","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsandstream%2Fralph-inferno","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsandstream%2Fralph-inferno/lists"}