Architecture — radioactive-ralph

This page describes the current architecture direction for the live product. The implementation still has gaps, but the contract is now clearer than it was: radioactive-ralph is a binary-first tool with in-code personas, and Claude Code is treated as a client of that binary over stdio MCP.

Core commitment

The repo is no longer trying to be all of these at once:

  • a Claude marketplace plugin

  • a family of slash-command skills

  • a binary

  • a durable HTTP MCP service

  • a provider-agnostic runtime

The active direction is narrower:

  1. One binary — radioactive_ralph

  2. One durable state model — repo config plus XDG/App Support runtime state

  3. One Claude integration path — stdio MCP

  4. One persona source of truth — code-defined Ralph variants

Product shape

Layer

Role

radioactive_ralph binary

The product boundary: init, plan store, supervisor, doctor, and MCP server

Claude Code MCP

Structured control plane into the binary

Variant profiles

Built-in Ralph personas that shape system prompt, safety posture, and runtime behavior

Provider bindings

Future abstraction for non-Claude agent CLIs

Repo-visible state

Every repo that uses Ralph has .radioactive-ralph/ alongside .git/:

.radioactive-ralph/
├── config.toml
├── .gitignore
├── local.toml
└── plans/
    ├── index.md
    └── <topic>-advisor.md

  • config.toml is committed repo policy.

  • local.toml is gitignored operator-local state.

  • plans/ contains the human-readable planning artifacts.

Machine-local state

Machine-local runtime state lives under the Ralph state root:

$XDG_STATE_HOME/radioactive-ralph/
└── <repo-hash>/
    ├── plans.db
    ├── sessions/
    ├── logs/
    └── worktrees/

This is where the durable plan DAG, runtime sessions, and per-repo transient state belong. Never store this under .claude/.

Claude integration

Claude Code is integrated through stdio MCP:

  • radioactive_ralph init registers the binary with claude mcp add

  • Claude spawns radioactive_ralph serve --mcp

  • the MCP server exposes plan and runtime control surface

  • the binary remains the authority over variant behavior and state

The abandoned complexity was trying to make plugin skills, service-managed HTTP, and binary control all equally primary. They are not.

Personas, not skills

Ralph has many personalities, but the source of truth is now the code:

  • internal/variant/ defines the behavioral profiles

  • internal/voice/ defines the Ralph voice layer

  • docs/variants/ explains each personality to operators

This keeps the canon in one place. A persona may eventually be surfaced through different front ends, but it should not require a separate parallel skill spec to exist.

Current provider reality

Today the runtime still assumes the claude CLI for agent execution. The code therefore still knows about Claude-specific concerns such as model tier names, reasoning effort, and CLI session behavior.

That is current implementation, not the long-term contract.

Provider direction

The target shape is a declarative provider binding layer inside repo config. Conceptually that means each repo can say:

  • which agent CLI to invoke

  • how to set model

  • how to set effort

  • how to append the Ralph persona prompt

  • how to pass the task/user prompt

  • what structured output format to expect back

That would allow the same Ralph personas to drive Claude, Codex, Gemini, OpenAI CLI tooling, or any other provider with the necessary bindings.

Current gaps

  • Fixit still writes markdown advice but does not yet fully populate the live DAG.

  • Plan gating is not yet properly repo-scoped.

  • run still exposes less safety/runtime wiring than the variant docs imply.

  • Provider bindings are still a design direction, not live code.

See state for the explicit status of those gaps.