radioactive-ralph runs your local AI-agent CLIs (Claude, Codex, OpenCode) as
supervised workers that can never block. It installs one executable that,
in supervisor mode, owns each agent's pseudo-terminal, watches every worker for
stalls and permission-prompts, and kills-and-reclaims instead of ever waiting.
Work is driven by a simple markdown plan, decomposed with pure heuristics (no
LLM), and a step is only "done" once the runtime verifies it — never
because an agent said so.
The authoritative core design is
docs/superpowers/specs/2026-07-16-supervisor-architecture-design.md.
Its historical native Windows PTY and service clauses are superseded by the
Windows SCM safety contract;
the decision trail is .agent-state/decisions.ndjson.
What it is
- One binary, two modes.
radioactive_ralph --supervisor is the long-lived
process that owns every agent's pty and holds all work open. Plain
radioactive_ralph is a dumb client: it discovers the supervisor over a
socket at an XDG path and renders a read-only view — it refuses to run without
a supervisor.
- The control invariant. An agent CLI can never block the system. Agents run
non-interactively under Ralph's pty; a watchdog surfaces any stall or
permission-prompt and the runtime kills-and-reclaims. Recovery is cheap
because state is durable.
- One user-level database. A single SQLite DB (under your XDG state dir) is
durable memory for all projects. Repos stay clean — no committed config
dir, no per-repo database. Projects are recognized by accumulated fingerprints
(git root-commit, remote, path), so identity survives
git init and moves.
- No personas. There are no variants. One mutating Ralph; behavior comes
from the task and its context, not roleplay.
- Markdown plans, verified completion. Plans are plain markdown decomposed
heuristically (heading = group, unordered list = parallel steps, ordered =
sequential). The orchestrator dispatches steps with scoped context and
verifies each against its acceptance criteria before marking it done.
- Local-only providers.
claude, codex, opencode — the agent loop and
tool execution run locally (hosted model inference is fine). A2A coordination
vocabulary comes from the official a2aproject/a2a-go.
- Observable multi-provider teams. Project config can declare
providers = ["claude", "codex", "opencode"]; Ralph assigns one supervised
worker per dispatched step across the pool. RALPH_MAX_PARALLEL is an
operator-selected process-wide emergency ceiling, not an optimal or
recommended team size.
Install
CLI
| Platform | Command |
|---|
| macOS (Homebrew cask) | brew tap jbcom/pkgs https://github.com/jbcom/pkgs && brew install --cask radioactive-ralph |
| Windows Scoop | scoop bucket add jbcom https://github.com/jbcom/pkgs && scoop install radioactive-ralph |
| Debian / Ubuntu | download the matching .deb, then sudo apt install ./radioactive-ralph_<version>_linux_<arch>.deb |
| Fedora / RHEL | download the matching .rpm, then sudo dnf install ./radioactive-ralph_<version>_linux_<arch>.rpm |
| macOS / Linux curl installer | curl -sSL https://jonbogaty.com/radioactive-ralph/install.sh |
Desktop app (GUI)
The desktop app is a graphical peer to the terminal UI on the same supervisor —
it watches and drives (approve, pause/resume, kill, import) from a window.
| Platform | Command / file |
|---|
| macOS (Homebrew cask) | brew install --cask radioactive-ralph-gui — opens cleanly, no Gatekeeper prompt |
| Linux (AppImage) | download the .AppImage from the latest release, chmod +x, run |
| macOS (direct) / Windows | best-effort .dmg / .exe downloads from the latest release |
Double-clicking the app opens the GUI; from a terminal, radioactive_ralph gui
does the same. The macOS app is ad-hoc signed and its cask removes quarantine;
the AppImage is unsigned but is covered by the signed, workflow-bound
gui-checksums.txt manifest; the
Windows executable is Authenticode-signed only when the optional SignPath
credentials are configured.
Quick start
# 1. Start the supervisor (owns everything; user/XDG-level, directory-independent)
radioactive_ralph --supervisor
# On macOS/Linux, install + start it as the user service:
radioactive_ralph service install
# 2. In a project directory, initialize it (registers the project in the user DB)
radioactive_ralph --init
# 3. Import a markdown plan; it is activated and the supervisor begins driving it
radioactive_ralph plan import plan.md
# 4. Watch and drive: the read-only terminal cockpit …
radioactive_ralph
# … or the desktop app (a GUI peer that can also approve/pause/kill/import).
# Install it from the "Desktop app" table above; `radioactive_ralph gui`
# (or double-clicking the installed app) opens it.
radioactive_ralph gui
The client refuses to run unless a supervisor is reachable, and tells you how to
start one. Nothing is written into your repository.
Windows: v0.22 disables native SCM install/start. Native foreground
--supervisor is a limited supervisor/client control plane only because
provider workers return ErrPTYUnsupported. Use WSL2 for functional
provider-backed execution. service status/uninstall exist only to remove
a prior development SCM registration.
The gui subcommand only opens a window in a GUI-enabled build — the
desktop-app installs (Homebrew cask, AppImage, .dmg/.exe). The CLI-only
installs (Homebrew CLI cask, Scoop, .deb/.rpm, the curl
installer) ship the terminal client; running gui there prints a note telling
you to install the desktop app. The Windows .exe is signed only once the
project's free SignPath enrollment is configured — until then Windows
SmartScreen may warn on first launch.
CLI surface
radioactive_ralph --supervisor # run the supervisor (owns agent ptys + the user DB)
radioactive_ralph # dumb client: discover the supervisor, read-only TUI
radioactive_ralph gui # desktop GUI client (watch + drive); needs a GUI-enabled build
radioactive_ralph --init # initialize / re-initialize the current project
radioactive_ralph plan import <f> # import a markdown plan and activate it
radioactive_ralph plan ls [--all] # list the current project's plans
radioactive_ralph doctor # environment checks
Docs
Contributing
See AGENTS.md (the canonical agent protocol) and
STANDARDS.md.
go build ./...
go test ./...
go test -race ./...
golangci-lint run
make docs-check
License
MIT. See LICENSE.
