How it's built.

Home

Local-first. The whole product runs on one Python process on your machine. There is no server you pay for, no SaaS to log into. The dashboard is just a static frontend served by the same daemon at localhost:3000.

The runner is the AI. Ralpharium doesn't replace Claude Code, Codex, or Aider — it runs them. You pick which one in the dashboard. Each iteration spawns the runner as a subprocess, the daemon captures stdout, parses what came out, and records the result. Swap runners by changing one config field.

The four input files the runner reads each iteration: PROMPT.md (instructions), AGENTS.md (rules), IMPLEMENTATION_PLAN.md (task list), and specs/*.md (acceptance criteria). The daemon parses all four and surfaces them on the dashboard.

┌─────────────┐    reads     ┌─────────────────────────┐    streams    ┌──────────────┐
│ your runner │ ──────────►  │   ralph studio daemon   │ ─────────────►│  dashboard   │
│ (codex /    │   PROMPT.md  │  • repo inspector       │   websocket   │ (operator)   │
│  claude /   │   PLAN.md    │  • plan parser          │               │              │
│  aider)     │   AGENTS.md  │  • spec coverage        │               │              │
│             │   specs/*    │  • backpressure runner  │               │              │
│             │   git diff   │  • iteration store      │               │              │
│             │              │  • RAM event stream     │               │              │
└─────────────┘              └─────────────────────────┘               └──────────────┘
                                       │
                                  .ralph/iterations.jsonl  (append-only history)

Three execution surfaces

Ralph artifacts

Every iteration starts by re-reading the same files. Studio parses each one and surfaces structure to the dashboard.

Plan parser

The parser reads checkbox tasks (- [ ], - [x], plus [/] in-progress, [!] blocked, [~] stale) and groups them by section. It picks "next" as the first pending task and raises warnings for repeated text, all-completed plans, and 24h+ staleness.

Iteration model

Each loop pass is one Iteration. Studio creates one when you click Start (or when your runner POSTs to /api/iterations) and finalizes it on success / failure / stop. The full record is appended to .ralph/iterations.jsonl — a flat file you can tail -f, grep, or ship anywhere.

{
  "id": "it_1736172000_a3f9c1d8",
  "number": 42,
  "mode": "build",
  "status": "passed",
  "started_at": 1736172000.12,
  "ended_at": 1736172094.55,
  "summary": "Add /api/specs endpoint",
  "files_changed": ["backend/main.py", "backend/specs.py"],
  "commit_sha": "9af2b7c",
  "test_status": "passed",
  "validation": [{"name": "Tests", "status": "passed"}],
  "command_output": "...",
  "failure_reason": null
}

The dashboard timeline lists the latest 30; click any row and the replay drawer fills with the prompt mode used, the validation results, the files changed, the tail of stdout, and the commit it produced.

Backpressure (validation)

Backpressure is just a name for "the loop stops when tests fail." Ralpharium looks for npm test / npm run lint / npm run build in your package.json and offers them as one-click checks. If you turn on stop_on_failure, a red check halts the loop before bad code lands. Same idea for git: turn on stop_if_dirty_before_run and Ralph won't start a new iteration on uncommitted changes.

RAM observability

Beyond the durable iteration log, Studio keeps a volatile RAM layer that the dashboard can stream live. Nothing here is written to disk — it's the live nervous system of the running daemon.

API surface

Everything is REST + a single WebSocket. The dashboard only uses these — your CLI can use them too.

GET   /api/state                 # aggregate first-paint snapshot
GET   /api/status                # mode, iter count, runner, branch, dirty
GET   /api/repo-state            # git + Ralph file detection
GET   /api/plan-health           # IMPLEMENTATION_PLAN.md parsed
GET   /api/spec-coverage         # specs/* mapped to plan + commits
GET   /api/backpressure          # auto-detected validation checks
GET   /api/guardrails            # PROMPT/AGENTS + suggestions
GET   /api/iterations?limit=N    # iteration history
GET   /api/iterations/{id}       # single iteration detail
POST  /api/iterations            # CLI hook: begin iteration
PATCH /api/iterations/{id}       # CLI hook: finish/update iteration

POST  /api/loop/{start|pause|resume|stop|panic}   # control
POST  /api/check/{id}            # run a backpressure check
POST  /api/runner                # set runner + command

GET   /api/ram                   # full volatile snapshot
GET   /api/ram/events            # ring buffer
GET   /api/ram/blackboard        # kv slots
GET   /api/ram/pressure          # memory pressure
POST  /api/ram/scratchpad        # pin a note
POST  /api/ram/checkpoints       # snapshot repo+plan

WS    /ws                        # live updates: status, iteration_*, ram_*, log

Stack & run

pip install -r backend/requirements.txt
python backend/main.py
# http://localhost:3000

# optional config
RALPH_REPO_PATH=/path/to/repo \
RALPH_RUNNER=claude \
RALPH_RUNNER_CMD="claude -p PROMPT.md" \
python backend/main.py