---
title: internal/agentdetect
description: Go API reference for the agentdetect package.
---

<!-- Code generated by gomarkdoc. DO NOT EDIT -->

# agentdetect

```go
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](<#Suggest>)
- [type DetectedCLI](<#DetectedCLI>)
  - [func Detect\(\) \[\]DetectedCLI](<#Detect>)
- [type Status](<#Status>)
  - [func \(s Status\) String\(\) string](<#Status.String>)


<a name="Suggest"></a>
## func [Suggest](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/agentdetect/detect.go#L189>)

```go
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\).

<a name="DetectedCLI"></a>
## type [DetectedCLI](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/agentdetect/detect.go#L64-L84>)

DetectedCLI is one probed agent CLI candidate.

```go
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
}
```

<a name="Detect"></a>
### func [Detect](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/agentdetect/detect.go#L163>)

```go
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".

<a name="Status"></a>
## type [Status](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/agentdetect/detect.go#L22>)

Status classifies one detected \(or expected\) agent CLI.

```go
type Status int
```

<a name="Supported"></a>The recognized Status values.

```go
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
)
```

<a name="Status.String"></a>
### func \(Status\) [String](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/agentdetect/detect.go#L48>)

```go
func (s Status) String() string
```

String renders the status name for logs/errors.

Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)