Ralpharium

The Ralph Loop, made observable. A local-first control plane for autonomous AI coding loops — Claude, Codex, Aider, or any shell command — with 8 specialized agents in shared memory, a live dashboard, and replayable iteration history.

Links: ralpharium.com · npm · X / Twitter

Requirements

Before npx ralpharium will work you need:

| What | Why | Check | |---|---|---| | Node 18+ | comes with npx | node -v | | Python 3.11+ | the daemon is FastAPI | python --version (or python3 --version) |

If Python is missing, install it from python.org (Windows / macOS) or brew install [email protected] / sudo apt install python3.12 python3-pip.

Already installed but Ralpharium can't find it? Set RALPH_PYTHON to the full path:

# PowerShell
$env:RALPH_PYTHON = "C:\Path\To\python.exe"
# bash / zsh
export RALPH_PYTHON=/path/to/python

FastAPI and uvicorn install automatically on first run — you don't have to do anything.

Real Claude / Codex / Aider iterations require those CLIs installed and authenticated separately. Ralpharium also has a safe-fallback runner so you can demo without auth.

Quickstart

npx ralpharium init     # scaffold the four Ralph artifacts in your repo
npx ralpharium start    # boot the daemon, opens dashboard at localhost:3000

That's it. Two commands. No accounts, no API keys, no cloud calls.

What is Ralpharium?

Ralpharium is a local-first dashboard and runner that turns the Ralph Wiggum technique (a bash loop that pipes a prompt file to an AI CLI on repeat) into an observable, controllable system. You point it at a repo, pick a runner, click Start. It runs the AI in a tight cycle, gates each pass on tests and lint, and shows you exactly what changed — every iteration, every commit, every failure — without anything leaving your machine.

It's not a replacement for Claude / Codex / Aider. It runs them. The runner is the AI; Ralpharium provides the context, validation, observation, and stop conditions around it.

What you get

• Operator dashboard at /dashboard — live iteration timeline, plan health, validation backpressure, spec coverage, guardrails, runtime panel. Start / pause / panic-stop. Point-and-click control.
• RAM debug page at /ram — under-the-hood live view: 8 agents, blackboard slots, event ring buffer, hex viewer of the shared-memory segment, scratchpad, checkpoints, runner process monitor.
• Architecture page at /tech — full system diagram and design notes.
• Continuous-loop runner with stop conditions: max iterations, stop on failure, stop if no commit produced, stop if tree dirty before run.
• Append-only iteration log at .ralph/iterations.jsonl — replayable history of every loop pass.
• Tiny Node CLI (ralpharium) for init, environment checks, launching pages.

Inspired by Ralph Loop

Ralph Loop by @ghuntley is a methodology, not a tool: run Claude in a bash while loop, treat it as a capable-but-naive executor, steer behavior with engineered context — PROMPT.md, AGENTS.md, IMPLEMENTATION_PLAN.md, specs/*.md — re-read every iteration. Backpressure (tests / lint / typecheck) is the steering mechanism. The plan is disposable. Convergence is eventual.

It works. But it has real pain points:

• Black box — all you see is bash stdout streaming past
• One monolithic prompt — plan, code, validate, classify all in one call
• Manual stop only — if Ralph rewrites the same file 5 times with the same error, you don't notice until you Ctrl-C
• No replay — past iterations live in git log at best
• No structured guardrails — stop conditions are whatever your bash script remembers to check

How Ralpharium upgrades it

| Pain point in vanilla Ralph Loop | Ralpharium's upgrade | |----------------------------------|----------------------| | Black box (just bash stdout) | Glass box. Live blackboard, hex view of the shared-memory segment, event ring buffer, per-agent drill-down with prompt + decision history, replayable JSONL on disk. | | One monolithic prompt | 8 specialized agents. spec_writer + researcher handle phase-1 context. planner + builder drive the build cycle. reviewer + debugger own validation backpressure. magpie + tagger capture and classify each iteration's output. | | .md files re-read from disk | 64KB shared memory. Agents pass structured work through an OS-level multiprocessing.shared_memory segment instead of re-reading the same files every iteration. Fewer disk hits, instant cross-agent visibility, observable as live JSON. | | Manual Ctrl-C | Real stop conditions. One-toggle gates: stop_on_failure, stop_if_no_commit, stop_if_dirty_before_run, max_iterations. Plus a thrash detector that pauses the loop when the same files modified 3+ times produce the same failure. | | Tail bash logs | Replayable iterations. Append-only .ralph/iterations.jsonl stores every iteration's mode, status, files changed, validation result, command output (last 4KB), commit SHA, and failure reason. | | Single-shell session | REST + WebSocket API. Any tool can POST /api/iterations to start a pass and PATCH when it finishes. The dashboard subscribes to a live WebSocket — multiple tabs and external clients see the same state. |

Inside an iteration

A single iteration is one full pass of the 8-agent cycle. The daemon orchestrates it; the dashboard streams every step over WebSocket. Here's the sequence, end to end:

1. Pre-flight — Planner + Researcher. The Planner reads IMPLEMENTATION_PLAN.md and picks the first unchecked task. The Researcher scans the repo (branch, dirty state, spec count) and writes that context to the shared blackboard so every other agent sees the same snapshot.

2. Build phase — Builder runs the subprocess. The Builder spawns your runner command (e.g. claude -p "$(cat PROMPT.md)") with cwd set to your repo. Stdout streams line-by-line into the RAM event log, parsed for errors and test mentions. The blackboard's last_error, test_output, and pid slots update in real time.

3. Backpressure — Reviewer + Debugger. When the subprocess exits, the Reviewer runs your validation gates (npm test / lint / typecheck / build) auto-detected from package.json. If anything fails, the Debugger classifies the failure and writes it to the blackboard. With stop_on_failure on, the loop halts here.

4. Post-loop — Magpie + Tagger. If the iteration produced a real commit, the Magpie collects the artifacts (commit SHA, files changed, scratchpad notes) and the Tagger classifies the iteration (feature / fix / refactor / docs).

5. Persist + broadcast. The full iteration record is appended to .ralph/iterations.jsonl. The daemon broadcasts a fresh snapshot over WebSocket — your dashboard timeline, RAM agent grid, plan health, and event stream all update without a refresh.

6. Loop or stop. The loop checks stop conditions. If clean, it goes back to step 1 and picks the next plan task. The thrash detector watches for "same files modified with same error 3+ times" and pauses you before tokens are wasted.

The four files Ralpharium reads

| File | Role | |------|------| | PROMPT.md | Per-iteration instruction. Re-read at the start of every iteration. | | AGENTS.md | Operational rules — build/test commands, scope limits, commit hygiene. | | IMPLEMENTATION_PLAN.md | Persistent task list. Parsed into completed / pending / blocked / stale. Drift warnings raised automatically. | | specs/*.md | Source-of-truth specs. Each is mapped against plan tasks and recent commits — covered, partial, drifting, or ignored. |

npx ralpharium init scaffolds all four with sensible starter content.

Commands

| Command | What it does | |---------|--------------| | npx ralpharium init | Scaffold PROMPT.md, AGENTS.md, IMPLEMENTATION_PLAN.md, specs/, .ralph/ | | npx ralpharium start | Boot daemon + open home page at localhost:3000 | | npx ralpharium dashboard | Boot daemon + open the dashboard | | npx ralpharium ram | Boot daemon + open the RAM debug page | | npx ralpharium tech | Boot daemon + open the architecture page | | npx ralpharium check | Diagnose Python + dependencies + Ralph files | | npx ralpharium smoke | Run backend smoke test (no HTTP) |

Flags: --port=N (default 3000), --no-open (skip auto-opening the browser).

Environment variables:

| Variable | Purpose | |----------|---------| | RALPH_REPO_PATH | Override which repo to watch (default: cwd) | | RALPH_DATA_DIR | Where iterations.jsonl lives (default: <repo>/.ralph) | | RALPH_RUNNER | codex / claude / aider / custom (default: claude) | | RALPH_RUNNER_CMD | Shell command to run each iteration | | RALPH_PYTHON | Full path to a Python 3.11+ interpreter | | PORT | Server port (default: 3000) |

Architecture

• Backend: Python 3.11+ FastAPI daemon, single Uvicorn process. WebSocket for live updates, REST for first paint. No database, no message queue.
• Shared memory: OS-level multiprocessing.shared_memory segment (64KB) holding the live blackboard JSON. The 8 agents read and write structured slots; everything is observable in real time.
• Frontend: Vanilla JS + CSS. No framework, no build step, no bundler. The dashboard at /dashboard and the RAM page at /ram are static files served by the daemon.
• Persistence: Append-only JSONL at .ralph/iterations.jsonl. Replayable, greppable, gitignorable.
• CLI: Tiny Node launcher (bin/ralph-studio.js) that spawns the Python daemon. The npm bin is ralpharium (and ralph-studio for back-compat).

Safety checklist for your first real run

Before you click Start on a real codebase:

• [ ] Commit or stash your own changes first. A dirty tree is a footgun for any iteration runner.
• [ ] Start with max_iterations = 1. Validate one full pass before letting it loop.
• [ ] Use a throwaway repo for the first real run. Don't hand a brand-new prompt to a production codebase.
• [ ] Enable stop_on_failure. The first failure usually surfaces a misunderstanding worth fixing in PROMPT.md.
• [ ] Enable stop_if_no_commit. An iteration that doesn't produce a commit usually means the runner didn't really do anything.
• [ ] Enable stop_if_dirty_before_run. Refuse to start a new iteration on uncommitted changes.
• [ ] Confirm the runner CLI is authenticated. Run claude --version / codex --version / aider --version first; do one interactive run to set up auth.
• [ ] Watch the /ram page during the first run. The event stream shows process output, exit codes, and blackboard updates in real time.

Roadmap

Shipped:

• Foundations — daemon, JSONL store, plan parser, RAM page
• 8 agents made observable — roster, drill-down grid, thrash detector, live broadcasts

Next (in progress):

• Cost telemetry per iteration — parse runner stdout for tokens, surface $/iteration
• Git-worktree-per-iteration sandbox — no edits land on main until validation passes
• Bidirectional question channel — agent writes a question, loop pauses, you reply
• Time + token budgets — kill runaway iterations after N seconds or M tokens

Soon:

• Daemon crash recovery — replay iterations.jsonl on boot
• Multi-client presence — two devs watching the same loop see each other
• Replay on a different model — re-run a past iteration on Sonnet vs Opus and diff
• Real per-agent LLM calls — phase 1 synthesizes agent activity; phase 3 = each agent is a real LLM call

North star:

• Self-spec'ing loops, multi-repo orchestration, visual diff approval, public agent marketplace

License

MIT.

Credit

Built on the Ralph Wiggum technique by @ghuntley. The methodology is theirs; Ralpharium is the observable substrate.