Ralpharium

The Ralph Loop, made observable.

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

   

CA: HPfUPHc7FF4azR7rj65hCsQcJ9ZSoj728fqZ6Wf1Loop

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

Two commands. No accounts, no API keys, no cloud calls. Real Claude / Codex / Aider iterations need those CLIs installed and authenticated separately — Ralpharium just orchestrates them locally.

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

If Python is missing, grab it from python.org (Windows / macOS), brew install python@3.12, or sudo apt install python3.12 python3-pip. Already installed but Ralpharium can't find it? Set RALPH_PYTHON to the full path.

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

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 + lint, and shows you exactly what changed — every iteration, every commit, every failure — without anything leaving your machine.

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.

A single iteration = one full pass of the 8-agent cycle. The daemon orchestrates it; the dashboard streams every step over WebSocket.

flowchart LR
    A[1. Pre-flight<br/>Planner + Researcher] --> B[2. Build phase<br/>Builder runs runner]
    B --> C[3. Backpressure<br/>Reviewer + Debugger]
    C --> D[4. Post-loop<br/>Magpie + Tagger]
    D --> E[5. Persist<br/>iterations.jsonl]
    E --> F{Stop conditions?}
    F -->|met| G[Stop]
    F -->|clean| A

Each owns a slot in a 64KB multiprocessing.shared_memory segment. Click any agent card on /ram to see its full prompt + decision history.

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 with engineered context. It works — but it has real pain points:

npx ralpharium init scaffolds all four with sensible starter content.

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

Environment variables:

Zero dependencies in the npm package itself. The whole thing fits in 22 files and 250 KB.

Before clicking Start on a real codebase:

• Commit or stash your own changes — a dirty tree is a footgun
• Start with max_iterations = 1 — validate one full pass before letting it loop
• Use a throwaway repo for the first real run — never give a brand-new prompt to production code
• Enable stop_on_failure — first failures usually surface a misunderstanding worth fixing in PROMPT.md
• Enable stop_if_no_commit — iterations that don't commit usually mean the runner did nothing
• Enable stop_if_dirty_before_run — refuse to start on uncommitted changes
• Confirm the runner CLI is authenticated — claude --version etc., do one interactive run first
• Watch /ram during the first run — event stream shows process output, exit codes, blackboard updates live

Built in the open. Every milestone is real work — no vapor.

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

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

• 💾 Daemon crash recovery — replay iterations.jsonl on boot
• 👥 Multi-client presence — two devs watching the same loop see each other's cursors
• 🔁 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 from lifecycle; phase 3 = each agent is a real LLM call with its own system prompt

• 🪞 Self-spec'ing loops · 🌐 multi-repo orchestration · 👁️ visual diff approval · 🛒 public agent marketplace

Open source, MIT, PRs welcome. The whole code base is < 5K LoC across backend/, frontend/, bin/. No build step, no framework — read the source, change a line, see the result.

git clone https://github.com/ctrlshifthash/Ralpharium
cd Ralpharium
npm start    # spawns the daemon against this repo

File issues at the GitHub issue tracker. Found a bug? Have a wild idea? Open a PR.

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

"Let Ralph Ralph." — the philosophy that started it all.

MIT. Do whatever. Just don't sue if Ralph Ralphs.