Get started¶

Install the binary¶

Platform	Command
macOS / Linuxbrew / WSL2+Linuxbrew	`brew tap jbcom/pkgs && brew install radioactive-ralph`
Windows Scoop	`scoop bucket add jbcom https://github.com/jbcom/pkgs && scoop install radioactive-ralph`
Windows Chocolatey	`choco install radioactive-ralph`
POSIX curl installer	`curl -sSL https://jonbogaty.com/radioactive-ralph/install.sh

Initialize a repo¶

Run the initializer at the repo root once:

radioactive_ralph init

That creates .radioactive-ralph/, writes the repo config files, scaffolds plans/index.md, and registers radioactive_ralph with Claude Code as a stdio MCP server unless you pass --skip-mcp.

Ask Fixit what should happen first¶

When you are starting from a plain-English goal, begin with Fixit Ralph:

radioactive_ralph run --variant fixit --advise \
  --topic finish-docs-pass \
  --description "finish the docs pass and line up the next implementation phase"

Today that writes an advisor report to .radioactive-ralph/plans/<topic>-advisor.md and, on first creation for that repo/topic slug, syncs the recommendation into the durable plan DAG every other Ralph depends on.

Launch a working persona¶

Once you have plan context, run the persona you actually want:

radioactive_ralph plan ls
radioactive_ralph run --variant green --foreground

Useful follow-up commands:

radioactive_ralph status --variant green
radioactive_ralph attach --variant green
radioactive_ralph stop --variant green

Core commands¶

Command	What it does
`radioactive_ralph init`	Set up `.radioactive-ralph/` and register Claude MCP
`radioactive_ralph run --variant fixit --advise`	Interpret a free-form goal, write the advisor report, and seed the durable plan
`radioactive_ralph run --variant <name>`	Launch a supervisor for a specific Ralph persona
`radioactive_ralph status --variant <name>`	Query a running supervisor over its Unix socket
`radioactive_ralph attach --variant <name>`	Stream supervisor events live
`radioactive_ralph stop --variant <name>`	Shut a supervisor down gracefully
`radioactive_ralph plan ls`	List plans in the durable plan store
`radioactive_ralph serve --mcp`	Run the stdio MCP server
`radioactive_ralph mcp register`	Register the stdio MCP server with Claude Code

Current requirements¶

git
claude CLI installed and authenticated
gh recommended for GitHub workflows

Claude is the current provider implementation. The product direction is broader: binary-first, persona-first, and eventually provider-agnostic.