Desktop GUI#

radioactive_ralph gui (or double-clicking the installed desktop app) opens the graphical client — a peer to the terminal TUI on the same supervisor socket. It shows the same live macro→meso→micro drill, but unlike the read-only TUI it can also drive: approve a task awaiting approval, pause/resume/abandon a plan, kill a worker, and import a plan — all from a window.

The GUI is a Go-native Fyne application with one visual identity across terminal and desktop: it shares the TUI’s semantic status palette (internal/statusbucket), so a running task is the same cyan and a paused plan the same orange whether you are in a terminal or a window.

Installing it#

The gui command opens a window only in a GUI-enabled build — the desktop app installs. The CLI-only installs ship the terminal client and print a note when you run gui there.

Platform

Install

macOS

brew install --cask radioactive-ralph (opens cleanly — no Gatekeeper prompt)

Linux

the .AppImage from the latest release — chmod +x, run

macOS (direct) / Windows

the .dmg / .exe from the latest release

Signing is the open-source way — no paid Apple or Microsoft credentials — but the current state differs per platform:

  • macOS: the .app is ad-hoc-signed and the Homebrew cask strips the quarantine attribute on install, so the cask opens with no Gatekeeper prompt (the direct-download .dmg still shows one).

  • Windows: the .exe becomes Authenticode-signed once the project’s free SignPath enrollment is configured; until then Windows SmartScreen may warn on first launch.

  • Linux: the AppImage is unsigned by convention and verified by its release checksum.

Launching#

  • From a terminal: radioactive_ralph gui.

  • By double-clicking the installed .app / AppImage / .exe: the binary detects that it was launched from a desktop context (no controlling terminal) and opens the GUI rather than the TUI.

  • Project scope: launched from a project directory, the GUI scopes to that project; launched from a file manager (working directory not a repo) it opens project-agnostic and lists the active plans across every project the supervisor knows — it never registers the launch directory as a new project. In project-agnostic mode you can still drive any plan or task the list shows — pause/resume/abandon, approve, and kill each act on a specific plan/task/worker id and need no project scope. Only importing a plan needs a project context (it targets the project you launched from), so launch from a project directory (or the gui subcommand inside a repo) when you want to import — the import affordance is hidden otherwise.

The window opens even before a supervisor is running: the header shows waiting for supervisor…, and it lights up to connected · up <duration> the moment one appears.

The three drill levels#

Level

Shows

Drive actions

Macro

Status header + the project’s plans (status chip + progress) + a “Recent activity” feed of recent project events

Import a plan

Meso

One plan’s tasks with per-task status

Pause / Resume / Abandon the plan; Approve a task awaiting approval

Micro

One task’s event timeline

Kill the worker running the task

Selecting a plan drills to meso; selecting a task drills to micro; the back buttons return. It is the same live snapshot the supervisor holds — no separate client-side state to drift.

How driving stays safe#

Every drive action funnels through the supervisor over the versioned IPC drive API — the supervisor remains the single writer of record, exactly as when the CLI imports a plan. The GUI never spawns or talks to an agent CLI directly, and killing a worker uses the same kill-and-reclaim path a watchdog kill would, so the control invariant (an agent can never block the system) is never bypassed.

All of the GUI’s reads and drive calls run off the UI thread, so a slow or unavailable supervisor can stale the view but never freeze the window.

Relationship to the CLI and TUI#

One binary. Plain radioactive_ralph is the read-only TUI; radioactive_ralph gui is the drive-capable desktop peer. Both discover the same supervisor and show the same state — pick whichever surface fits the moment.