This is the canonical first-time flow. Use the package-manager path that matches your platform, then drop into the common post-install section.

1a. Homebrew (macOS, Linux, WSL2 + Linuxbrew)¶

# Explicit URL form — the repo is named `pkgs`, not `homebrew-pkgs`,
# so the convention-shortcut `brew tap jbcom/pkgs` alone doesn't
# resolve. Pass the URL and brew taps it correctly.
brew tap jbcom/pkgs https://github.com/jbcom/pkgs
brew install radioactive-ralph
radioactive_ralph --version

Expected: the version string matches whatever tag you’re installing (e.g. 0.8.1 (99536d0, built 2026-04-16T...)).

1b. Scoop (Windows)¶

scoop bucket add jbcom https://github.com/jbcom/pkgs
scoop install radioactive-ralph
radioactive_ralph --version

1c. Chocolatey (Windows)¶

choco install radioactive-ralph
radioactive_ralph --version

Chocolatey publishing is gated behind the repo’s ENABLE_CHOCOLATEY variable; older releases may not have a nupkg. Fall back to Scoop if choco install reports “not found”.

1d. curl installer (macOS, Linux, WSL2)¶

curl -sSL https://jonbogaty.com/radioactive-ralph/install.sh | sh
radioactive_ralph --version

The installer writes to /usr/local/bin if writable, else ~/.local/bin. On the latter, make sure ~/.local/bin is on $PATH.

2. Initialize the repo¶

cd into any git repo and run:

radioactive_ralph init

This scaffolds .radioactive-ralph/ with:

config.toml — operator choices (committed)
local.toml — machine-local overrides (gitignored)
plans/index.md — human-readable plan index

Re-runnable. Pass --yes for non-interactive (CI) mode, or --force to overwrite an existing config.toml.

3. Verify your environment¶

radioactive_ralph doctor

Expected OK lines: git, your provider CLI (claude, codex, or gemini), optional service-manager hook (launchd on macOS, systemd on Linux, SCM on Windows). See Provider auth if a provider check fails.

4. Start the repo-scoped runtime¶

radioactive_ralph service start

Runs the durable repo service in the foreground. On launchd/systemd, you’ll more commonly service install (see Service runbook) which registers the runtime to start at login. For a first run, keep it in the foreground so you can see the control-plane logs.

In another terminal:

radioactive_ralph status --json

Expected: a JSON body with repo_path, pid, started_at, and an empty workers array. If you see no service socket at <path>, the service isn’t running yet — go back to step 4.

5. Create your first plan¶

radioactive_ralph run --variant fixit --advise --topic bootstrap

Fixit runs its six-stage plan-creation pipeline against the repo and:

Writes .radioactive-ralph/plans/bootstrap-advisor.md (the human-readable plan)
Emits the same plan into the plan DAG (durable SQLite under your XDG state dir)
Prints the next-step command

See the fixit delegation guide for the full pipeline.

6. Supervise a plan¶

With a plan in place, any non-fixit variant can claim tasks:

radioactive_ralph run --variant grey

The supervisor polls the DAG for ready tasks, dispatches each to the provider subprocess (your configured Claude / Codex / Gemini), and marks tasks done/failed based on acceptance criteria.

7. Open the cockpit¶

radioactive_ralph tui

Shows active plans, workers, recent events. See the TUI guide for keyboard shortcuts and drilldowns.

When something goes wrong¶

See Troubleshooting for the common failure modes (stale heartbeat, dead socket, provider CLI missing).