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

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

# variant

```go
import "github.com/jbcom/radioactive-ralph/internal/variant"
```

Package variant defines the ten Ralph behavior profiles.

Each variant is a distinct operating mode with its own parallelism, model tiering, commit cadence, termination policy, tool allowlist, safety floors, and capability\-bias preferences. The Profile struct is the canonical source of truth the supervisor reads to decide how to spawn and manage Claude subprocesses.

Each profile is registered from its own file \(blue.go, grey.go, ...\) so any operator can read the full definition of a single variant without wading through the others. The operator\-facing narrative lives in docs/variants/.

## Index

- [Constants](<#constants>)
- [Variables](<#variables>)
- [func MustRegister\(p Profile\)](<#MustRegister>)
- [func Register\(p Profile\) error](<#Register>)
- [func ResetRegistryForTesting\(\)](<#ResetRegistryForTesting>)
- [type BiasCategory](<#BiasCategory>)
- [type BiasSnippet](<#BiasSnippet>)
- [type IsolationMode](<#IsolationMode>)
- [type LFSMode](<#LFSMode>)
- [type Model](<#Model>)
- [type Name](<#Name>)
- [type ObjectStoreMode](<#ObjectStoreMode>)
- [type Profile](<#Profile>)
  - [func All\(\) \[\]Profile](<#All>)
  - [func Lookup\(name string\) \(Profile, error\)](<#Lookup>)
  - [func \(p Profile\) CanMutateViaBash\(\) bool](<#Profile.CanMutateViaBash>)
  - [func \(p Profile\) HasGate\(\) bool](<#Profile.HasGate>)
  - [func \(p Profile\) ModelForStage\(s Stage\) Model](<#Profile.ModelForStage>)
  - [func \(p Profile\) Validate\(\) error](<#Profile.Validate>)
  - [func \(p Profile\) WritesAllowed\(\) bool](<#Profile.WritesAllowed>)
- [type SafetyFloors](<#SafetyFloors>)
- [type Stage](<#Stage>)
- [type SyncSource](<#SyncSource>)
- [type TerminationPolicy](<#TerminationPolicy>)


## Constants

<a name="ToolAgent"></a>Tool names that appear in allow/deny lists. Mirrors Claude Code's built\-in tools.

```go
const (
    ToolAgent      = "Agent"
    ToolBash       = "Bash"
    ToolEdit       = "Edit"
    ToolGlob       = "Glob"
    ToolGrep       = "Grep"
    ToolRead       = "Read"
    ToolWrite      = "Write"
    ToolTaskCreate = "TaskCreate"
    ToolTaskUpdate = "TaskUpdate"
    ToolTaskList   = "TaskList"
)
```

## Variables

<a name="ErrNotFound"></a>ErrNotFound indicates a Lookup for an unregistered variant.

```go
var ErrNotFound = errors.New("variant: not found")
```

<a name="MustRegister"></a>
## func [MustRegister](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/registry.go#L35>)

```go
func MustRegister(p Profile)
```

MustRegister panics on validation failure. Used by built\-in variant init functions where a validation error is a programmer bug.

<a name="Register"></a>
## func [Register](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/registry.go#L23>)

```go
func Register(p Profile) error
```

Register adds profile to the global registry after validation. Intended to be called from variant package init functions. Returns an error rather than panicking so tests can exercise invalid profiles.

<a name="ResetRegistryForTesting"></a>
## func [ResetRegistryForTesting](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/registry.go#L68>)

```go
func ResetRegistryForTesting()
```

ResetRegistryForTesting clears the registry and re\-registers the built\-in variants. Tests that mutate the registry call this from a t.Cleanup to avoid bleeding state between tests.

<a name="BiasCategory"></a>
## type [BiasCategory](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/variant.go#L146>)

BiasCategory identifies a helper\-capability bias slot declared by the variant. Matches the keys the operator configures in \[capabilities\] in .radioactive\-ralph/config.toml.

```go
type BiasCategory string
```

<a name="BiasReview"></a>Bias categories that a variant may declare snippets for. Each maps to a \[capabilities\] key in config.toml.

```go
const (
    BiasReview         BiasCategory = "review"
    BiasSecurityReview BiasCategory = "security_review"
    BiasDocsQuery      BiasCategory = "docs_query"
    BiasBrainstorm     BiasCategory = "brainstorm"
    BiasDebugging      BiasCategory = "debugging"
)
```

<a name="BiasSnippet"></a>
## type [BiasSnippet](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/variant.go#L162>)

BiasSnippet is the system\-prompt injection used when a bias slot has a matching helper in the inventory.

Placeholder: \{skill\} expands to the chosen helper's full name.

```go
type BiasSnippet string
```

<a name="IsolationMode"></a>
## type [IsolationMode](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/variant.go#L46>)

IsolationMode controls where Ralph does its work relative to the operator's repo. See docs/reference/architecture.md for the full four\-knob explanation.

```go
type IsolationMode string
```

<a name="IsolationShared"></a>

```go
const (
    // IsolationShared runs against the operator's actual repo directory.
    // Only valid for variants that exclude Edit and Write from the tool
    // allowlist — enforced by Validate.
    IsolationShared IsolationMode = "shared"

    // IsolationShallow does a `git clone --depth=1` into XDG state.
    IsolationShallow IsolationMode = "shallow"

    // IsolationMirrorSingle is full `git clone --mirror` plus exactly one
    // worktree at a time.
    IsolationMirrorSingle IsolationMode = "mirror-single"

    // IsolationMirrorPool is a mirror clone plus N parallel worktrees.
    IsolationMirrorPool IsolationMode = "mirror-pool"
)
```

<a name="LFSMode"></a>
## type [LFSMode](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/variant.go#L94>)

LFSMode controls LFS handling.

```go
type LFSMode string
```

<a name="LFSFull"></a>

```go
const (
    // LFSFull clones LFS content normally.
    LFSFull LFSMode = "full"

    // LFSOnDemand fetches LFS content only when a task touches it.
    LFSOnDemand LFSMode = "on-demand"

    // LFSPointersOnly skips LFS blobs entirely.
    LFSPointersOnly LFSMode = "pointers-only"

    // LFSExcluded refuses tasks that touch LFS paths with a clear error.
    LFSExcluded LFSMode = "excluded"
)
```

<a name="Model"></a>
## type [Model](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/variant.go#L124>)

Model identifies a specific Claude model tier.

```go
type Model string
```

<a name="ModelHaiku"></a>Model tiers used by variant profiles.

```go
const (
    ModelHaiku  Model = "haiku"
    ModelSonnet Model = "sonnet"
    ModelOpus   Model = "opus"
)
```

<a name="Name"></a>
## type [Name](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/variant.go#L26>)

Name is the canonical variant identifier used internally in this package \(e.g. "blue", "fixit"\). This is the operator\-facing CLI \-\-variant value and the key used by voice.Variant.

Docs and CLI use the longer "\-ralph" display form in prose \("blue\-ralph", "fixit\-ralph"\), but the code keeps the shorter form because every identifier in this package is already variant\-scoped.

```go
type Name string
```

<a name="Blue"></a>The ten variants. Ordered from safest to most destructive, loosely matching the "hulk scale" documented in the PRD.

```go
const (
    Blue         Name = "blue"          // read-only observer
    Grey         Name = "grey"          // mechanical single-pass hygiene
    Green        Name = "green"         // default workhorse
    Red          Name = "red"           // single-cycle incident response
    Professor    Name = "professor"     // plan → execute → reflect
    Fixit        Name = "fixit"         // advisor + ROI-scored N-cycle bursts; sole variant that recommends peers
    Immortal     Name = "immortal"      // multi-day resilient loop
    Savage       Name = "savage"        // max throughput, gated
    OldMan       Name = "old-man"       // forceful imposition, gated
    WorldBreaker Name = "world-breaker" // all-opus, gated
)
```

<a name="ObjectStoreMode"></a>
## type [ObjectStoreMode](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/variant.go#L66>)

ObjectStoreMode applies to the mirror\-\* isolation modes.

```go
type ObjectStoreMode string
```

<a name="ObjectStoreReference"></a>

```go
const (
    // ObjectStoreReference borrows objects from operator's repo via
    // --reference --dissociate=false. Fast clone, shared objects.
    ObjectStoreReference ObjectStoreMode = "reference"

    // ObjectStoreFull clones fully independently. Destructive variants
    // pin this — they cannot be overridden to Reference without an
    // explicit two-step operator confirmation.
    ObjectStoreFull ObjectStoreMode = "full"
)
```

<a name="Profile"></a>
## type [Profile](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/variant.go#L203-L228>)

Profile is the canonical description of a variant.

```go
type Profile struct {
    Name                 Name
    Description          string // one-liner shown in `radioactive_ralph --help` and `radioactive_ralph init`
    Isolation            IsolationMode
    MaxParallelWorktrees int
    Models               map[Stage]Model // stage → model
    ToolAllowlist        []string        // Claude Code tool names
    Termination          TerminationPolicy
    CycleLimit           int    // meaningful only for NCycles
    ConfirmationGate     string // CLI flag like "--confirm-burn-budget"; empty = no gate
    ObjectStoreDefault   ObjectStoreMode
    SyncSourceDefault    SyncSource
    LFSModeDefault       LFSMode
    SafetyFloors         SafetyFloors
    SkillBiases          map[BiasCategory]BiasSnippet

    // ShellExplicitlyTrusted lets a shared-isolation variant include
    // Bash in its allowlist despite the structural "shared = read-only"
    // invariant. Bash is strictly more powerful than Edit+Write (it can
    // commit, rm, network-exec), so permitting it under shared
    // isolation is an explicit trust decision the profile declaration
    // must own. Blue sets it to true because its runtime posture restricts
    // Bash to read-focused queries; other
    // shared variants must follow the same discipline or refuse Bash.
    ShellExplicitlyTrusted bool
}
```

<a name="All"></a>
### func [All](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/registry.go#L54>)

```go
func All() []Profile
```

All returns every registered profile, sorted by Name.

<a name="Lookup"></a>
### func [Lookup](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/registry.go#L43>)

```go
func Lookup(name string) (Profile, error)
```

Lookup returns the profile for name \(case\-insensitive match\). Returns ErrNotFound if name isn't registered.

<a name="Profile.CanMutateViaBash"></a>
### func \(Profile\) [CanMutateViaBash](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/profile.go#L24>)

```go
func (p Profile) CanMutateViaBash() bool
```

CanMutateViaBash reports whether Bash is in the allowlist. Bash is strictly more powerful than Edit\+Write — it can run \`git commit\`, \`rm \-rf\`, curl\+pipe\-to\-sh, and anything else. For shared\-isolation variants, this is a backdoor around WritesAllowed unless the variant explicitly opts into it via ShellExplicitlyTrusted.

<a name="Profile.HasGate"></a>
### func \(Profile\) [HasGate](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/profile.go#L34>)

```go
func (p Profile) HasGate() bool
```

HasGate reports whether the variant requires a confirmation flag.

<a name="Profile.ModelForStage"></a>
### func \(Profile\) [ModelForStage](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/profile.go#L84>)

```go
func (p Profile) ModelForStage(s Stage) Model
```

ModelForStage returns the model configured for the given stage, or the model for StageExecute if no specific stage is set. Returns ModelSonnet as the last\-ditch default.

<a name="Profile.Validate"></a>
### func \(Profile\) [Validate](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/profile.go#L40>)

```go
func (p Profile) Validate() error
```

Validate ensures the profile is internally consistent. Called by Register so new or edited variants fail fast with actionable errors.

<a name="Profile.WritesAllowed"></a>
### func \(Profile\) [WritesAllowed](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/profile.go#L10>)

```go
func (p Profile) WritesAllowed() bool
```

WritesAllowed reports whether the variant's tool allowlist permits Edit or Write. Shared\-isolation variants must return false.

<a name="SafetyFloors"></a>
## type [SafetyFloors](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/variant.go#L181-L200>)

SafetyFloors pins specific fields that cannot be weakened by config.toml, env vars, or single\-flag CLI overrides.

```go
type SafetyFloors struct {
    // ObjectStore pinned to a specific value. Zero string means
    // "no pin, respect config/defaults."
    ObjectStore ObjectStoreMode

    // RefuseDefaultBranch prevents runs on main/master/etc.
    RefuseDefaultBranch bool

    // FreshConfirmPerInvocation means the confirmation gate must be
    // passed on every single `radioactive_ralph run` — never cached in config.
    FreshConfirmPerInvocation bool

    // RefuseServiceContext means the variant will not run when detected
    // under launchd/systemd (savage, old-man, world-breaker).
    RefuseServiceContext bool

    // RequireSpendCap means `radioactive_ralph run` fails without a cap value
    // either via --spend-cap-usd flag or [variants.X] spend_cap_usd.
    RequireSpendCap bool
}
```

<a name="Stage"></a>
## type [Stage](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/variant.go#L113>)

Stage identifies which phase of a variant's workflow a particular session spawn is for. Variants with a single stage \(grey, fixit\) always use StageExecute.

```go
type Stage string
```

<a name="StagePlan"></a>Stages enumerate the phases a variant may spawn subprocesses for.

```go
const (
    StagePlan    Stage = "plan"
    StageExecute Stage = "execute"
    StageReflect Stage = "reflect"
    StageReview  Stage = "review"
)
```

<a name="SyncSource"></a>
## type [SyncSource](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/variant.go#L80>)

SyncSource controls where the mirror fetches from.

```go
type SyncSource string
```

<a name="SyncSourceLocal"></a>

```go
const (
    // SyncSourceLocal pulls from operator's local repo via file:// remote.
    SyncSourceLocal SyncSource = "local"

    // SyncSourceOrigin pulls from the real origin (GitHub/GitLab/...).
    SyncSourceOrigin SyncSource = "origin"

    // SyncSourceBoth configures both remotes; fetch from local, push to origin.
    SyncSourceBoth SyncSource = "both"
)
```

<a name="TerminationPolicy"></a>
## type [TerminationPolicy](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/variant/variant.go#L134>)

TerminationPolicy classifies how a variant ends.

```go
type TerminationPolicy string
```

<a name="TerminationSinglePass"></a>Termination policies — how a variant's loop concludes.

```go
const (
    TerminationSinglePass TerminationPolicy = "single-pass" // one pass, exit
    TerminationNCycles    TerminationPolicy = "n-cycles"    // N cycles then exit with summary
    TerminationInfinite   TerminationPolicy = "infinite"    // runs until operator stops
)
```

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