agentdetect

import "github.com/jbcom/radioactive-ralph/internal/agentdetect"

Package agentdetect probes the local PATH for known agent CLIs and classifies each as Supported, Deprecated, RemoteDelegating, or Unknown, per spec docs/superpowers/specs/2026-07-16-supervisor-architecture-design.md §9 (“Providers (local-only)”): “local-only” means no cloud control surface in the loop — calling a hosted model API for inference is fine, but the agent SESSION itself must not be owned by a remote service.

Detect never runs a full agent turn; it only checks exec.LookPath and, for CLIs it finds, captures `–version` output. This keeps detection side-effect-free and fast enough to run on every supervisor/client startup.

Index

• func Suggest(detected []DetectedCLI) []string

• type DetectedCLI

  • func Detect() []DetectedCLI

• type Status

  • func (s Status) String() string

func Suggest

func Suggest(detected []DetectedCLI) []string

Suggest returns the names of every detected CLI classified Supported and actually found on PATH — the provider names radioactive_ralph should offer the user for this machine (e.g. during `radioactive_ralph init` provider selection).

type DetectedCLI

DetectedCLI is one probed agent CLI candidate.

type DetectedCLI struct {
    // Name is the candidate's canonical name (the PATH lookup key), e.g.
    // "claude", "codex", "opencode", "gemini", "cursor-agent", "cursor",
    // "agy".
    Name string

    // Path is the resolved executable path, empty if not found on PATH.
    Path string

    // Version is the captured `--version` output (trimmed), empty if
    // the binary was not found or --version failed/produced nothing.
    Version string

    // Status classifies this CLI. See the Status constants.
    Status Status

    // Reason explains the Status, especially for Deprecated,
    // RemoteDelegating, and Unknown, where the classification is not
    // self-evident from the name alone.
    Reason string
}

func Detect

func Detect() []DetectedCLI

Detect probes PATH for every known agent CLI candidate and returns one DetectedCLI per candidate name, in the fixed order of the candidates table above. A candidate not found on PATH is still returned (Path and Version empty) so callers can report “not installed” distinctly from “installed but unsupported”.

type Status

Status classifies one detected (or expected) agent CLI.

type Status int

The recognized Status values.

const (
    // Supported means the CLI runs a fully local agent session — no
    // forced cloud project/dashboard/session ownership in the loop —
    // and radioactive_ralph has (or plans) a runner for it.
    Supported Status = iota

    // Deprecated means the CLI/backend has been formally retired
    // upstream; radioactive_ralph will not add or keep a runner for it.
    Deprecated

    // RemoteDelegating means the CLI hands the actual agent session off
    // to a remote/cloud-hosted control surface — it fails the
    // local-only bar even though it runs as a local binary.
    RemoteDelegating

    // Unknown means detection found the binary but could not confirm
    // which bucket it belongs in (e.g. its local-vs-cloud behavior is
    // unconfirmed), or the binary is not an agent CLI at all (e.g. an
    // editor that happens to share a name with an agent CLI).
    Unknown
)

func (Status) String

func (s Status) String() string

String renders the status name for logs/errors.

Generated by gomarkdoc