radioactive-ralph

A supervised-execution runtime for local AI-agent CLIs.

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

• Getting started
• Architecture
• Design spec
• Self-test — have Ralph verify Ralph on a real plan

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.