Get started

Install the binary

The stable CLI install surface is the Homebrew CLI cask, Scoop, direct .deb/.rpm packages, and the curl installer. The stable GUI paths are the Homebrew GUI cask and Linux AppImage. Direct .dmg and .exe downloads are best-effort alternatives.

The two modes

radioactive_ralph is one binary that runs in two modes:

• radioactive_ralph --supervisor — the long-lived supervisor. It owns every agent's pty, holds all work open, serves the discovery socket, runs the reaper, and owns the one user-level SQLite database that is durable memory for every project on the machine. Working directory is irrelevant to it.
• radioactive_ralph (no flag) — the dumb client. It discovers the running supervisor and renders a read-only TUI. It refuses to run if no supervisor answers.

Start the supervisor once per machine, then run the client from any project directory.

Start the supervisor

radioactive_ralph --supervisor

This blocks in the foreground. On macOS and Linux, install it as an OS service for daily use so it survives logout/reboot/crash:

radioactive_ralph service install
radioactive_ralph service status

See the service runbook. Native Windows has only a limited foreground control plane in v0.22: keep using radioactive_ralph --supervisor, because provider workers return ErrPTYUnsupported and SCM install/start is disabled. WSL2 with the Linux build and systemd --user is the supported functional Windows route.

Initialize a project

From inside a repo (or any directory), register it with the running supervisor:

radioactive_ralph --init

This identifies the project by accumulated fingerprints (git root-commit + remote + absolute path, so identity survives git init and directory moves) and stores its config in the one user-level database. Nothing is written into the repo — no committed config directory, no per-repo database.

Running plain radioactive_ralph in a directory the supervisor doesn't know about auto-routes to the same initialization, so --init is rarely needed by hand.

Import a plan

A plan is plain markdown, decomposed heuristically (heading = group, unordered list = parallel steps, ordered = sequential). Import one to activate it — the supervisor's periodic dispatch loop then drives its ready steps:

radioactive_ralph plan import plan.md
radioactive_ralph plan ls          # confirm it is active

A step opts into mechanical, orchestrator-verified completion with an inline marker: `accept: <shell command>` (re-run in the project checkout and must exit 0) or `accept-file: <path>` (must exist). A step without a marker is judgment-only. Either way, completion is verified by the runtime, never inferred from a worker terminating.

Run the client

radioactive_ralph

In a terminal, this renders the read-only macro/meso/micro TUI showing the current project's plan and live agent activity. Piped or non-interactive (CI, go test), it prints a single status line instead of launching the TUI.

Or use the desktop app

radioactive_ralph gui

The desktop app is a graphical peer to the terminal UI on the same supervisor — same macro→meso→micro drill, but it can also drive: approve a task awaiting approval, pause/resume/abandon a plan, kill a worker, and import a plan from a window. Install it with brew install --cask radioactive-ralph-gui (macOS), the Linux .AppImage, or the Windows .exe from the releases page; double-clicking the installed app opens the GUI directly. It opens even before a supervisor is running and lights up when one appears.

Launched from a project directory, the app scopes to that project; launched by double-clicking from a file manager (where the working directory isn't a repo) it opens project-agnostic and lists every project the supervisor knows — it never registers the launch directory as a new project.

Check your environment

radioactive_ralph doctor

Reports whether git, a supported provider CLI (claude, codex, opencode), and the platform service manager are available. See Provider auth if a provider check fails.

Current requirements

• git
• at least one shipped provider CLI installed and authenticated:
  • claude
  • codex
  • opencode
• gh recommended for GitHub workflows

Providers are local-only capability bindings: the CLI owns its own agent loop and tool execution locally, even when it calls a hosted model for inference. gemini was removed as a shipped provider (CLI deprecated 2026-06-18); cursor-agent is excluded because it delegates the session to Cursor's cloud.