radioactive-ralph

Autonomous continuous development orchestrator for Claude Code.

What it is

radioactive-ralph drives Claude Code across a portfolio of git repos — continuously, without human intervention. It ships in two modes:

1. As a Claude Code plugin — a family of ten /ralph variants you run directly inside a Claude Code session. No separate daemon, no API key setup, no subprocess orchestration.
2. As a standalone Python daemon — pip install radioactive-ralph and run ralph run to get a persistent loop that survives context resets, spawns claude --print subprocesses, and lives outside any Claude Code session.

The only time you should be engaged is to brainstorm the vision.

Ralph has many forms

radioactive-ralph is not one skill. It's a family of ten, each a genuinely distinct operating mode with its own model tiering, parallelism, tool allowlist, and termination condition. See the variants index for more details.

Install as a Claude Code plugin

# Add this repo as a marketplace
claude plugins marketplace add github:jbcom/radioactive-ralph

# Install
claude plugin install radioactive-ralph@radioactive-ralph

# Then, inside Claude Code:
/green-ralph

All ten variants are installed at once. Use whichever you need per-session.

Install as a standalone daemon

# Run instantly — no install required
uvx radioactive-ralph run

# Or install permanently
pip install radioactive-ralph
ralph run

How the daemon mode works

┌─────────────────────────────────────────────────────┐
│                  radioactive-ralph                   │
│                   (Python daemon)                    │
│                                                      │
│  scan PRs → merge ready → review → address feedback  │
│       → discover work → spawn agents → loop          │
│                                                      │
│  State: ~/.radioactive-ralph/state.json              │
└──────────────┬──────────────────────────────────────┘
               │ spawns
               ▼
┌─────────────────────────────────────────────────────┐
│            claude CLI subprocesses                   │
│        (one per repo, run in parallel)               │
│                                                      │
│  Each agent: reads context, does work, opens PR      │
└─────────────────────────────────────────────────────┘

Model tiering

Each variant has its own model tiering policy — see the individual skill READMEs.

Configuration

Create ~/.radioactive-ralph/config.toml:

[orgs]
arcade-cabinet = "~/src/arcade-cabinet"
jbcom = "~/src/jbcom"

bulk_model = "claude-haiku-4-5-20251001"
default_model = "claude-sonnet-4-6"
deep_model = "claude-opus-4-6"
max_parallel_agents = 5

Set ANTHROPIC_API_KEY in your environment (daemon mode only — the plugin mode uses your existing Claude Code session).

Commands (daemon mode)

ralph run               # Start the daemon
ralph dashboard         # Open the live Rich terminal dashboard (reads state)
ralph status            # Show current state
ralph discover          # Show discovered work items
ralph pr list           # List all open PRs with classification
ralph pr merge          # Merge all MERGE_READY PRs
ralph doctor            # Run diagnostic health checks on the environment
ralph doctor --json     # Same checks, JSON output for CI/scripting
ralph stop              # Stop the running daemon
ralph install-skill     # Install a skill variant into ~/.claude/skills/

The dashboard command is read-only — it tails ~/.radioactive-ralph/state.json every second and renders a live multi-panel view (PRs, work queue, active agents, recent Ralph events, and stats footer). Run it in a second terminal alongside ralph run. Theme it with any variant: ralph dashboard -v old-man-ralph.

Personality

radioactive-ralph logs in the voice of Ralph Wiggum. Every variant has its own color scheme and quote set. The messages are variant-aware, event-aware, and randomly selected — so Ralph stays surprising while you watch him do 400 cycles. Yes, really.

[green-ralph] I dressed myself! And now I'm running!
[green-ralph] Cycle 1! I'm doing cycle 1! That's where I'm a developer!
[green-ralph] Scanning 12 repos for pull requests. I can see them with my eyes!
[green-ralph] Found 18 open pull requests across 12 repos! I found them!
[green-ralph] Merging PR #142 in radioactive-ralph. Squash! Like the game!
[green-ralph] PR #142 merged! Everybody's hugging!
[green-ralph] Sleeping for 30 seconds. Oh boy, sleep! That's where I'm a Viking!

See src/radioactive_ralph/ralph_says.py for the full personality module.

Requirements

• Python 3.12+
• claude CLI installed and authenticated (claude login)
• gh CLI installed and authenticated (gh auth login)
• ANTHROPIC_API_KEY set in environment (daemon mode only)

Contributing

See AGENTS.md for agentic operating protocols, STANDARDS.md for code quality rules, and CONTRIBUTING.md for the contribution workflow.

git clone git@github.com:jbcom/radioactive-ralph.git
cd radioactive-ralph
uv sync --all-extras
uv run pytest

License

MIT. See LICENSE.

# Install vhs once
brew install vhs    # or: go install github.com/charmbracelet/vhs@latest

# Record — the tape file is the source of truth
./scripts/record-demo.sh