config

package
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 22, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package config provides configuration management for ralphex with embedded defaults.

Index

Constants

View Source
const (
	ExecutorClaude = ""
	ExecutorCodex  = "codex"
)

Executor mode constants for the Config.Executor field. ExecutorClaude is the default — the empty string is intentional so that an unset `executor` field in config (or no flag on the CLI) resolves to the claude pipeline without users having to spell it out. ExecutorCodex is the opt-in first-class --codex path.

Variables

This section is empty.

Functions

func DefaultConfigDir added in v0.5.0

func DefaultConfigDir() string

DefaultConfigDir returns the default configuration directory path. returns ~/.config/ralphex/ on all platforms. if os.UserHomeDir() fails, falls back to ./.config/ralphex/ silently - this allows the tool to work even in unusual environments.

func DumpDefaults added in v0.12.0

func DumpDefaults(dir string) error

DumpDefaults extracts all embedded defaults (raw, uncommented) to the specified directory. creates config, prompts/, agents/ structure under dir.

func InitLocal added in v0.26.0

func InitLocal(dir string) error

InitLocal creates a local .ralphex/ configuration directory with commented-out defaults. uses the same Install() logic as global config setup - existing customized files are preserved. returns error if dir is empty.

Types

type ColorConfig added in v0.2.0

type ColorConfig struct {
	Task       string // task execution phase
	Review     string // review phase
	Codex      string // codex external review
	ClaudeEval string // claude evaluation of codex output
	Warn       string // warning messages
	Error      string // error messages
	Signal     string // completion/failure signals
	Timestamp  string // timestamp prefix
	Info       string // informational messages
}

ColorConfig holds RGB values for output colors. each field stores comma-separated RGB values (e.g., "255,0,0" for red).

type Config

type Config struct {
	ClaudeCommand string `json:"claude_command"`
	ClaudeArgs    string `json:"claude_args"`
	ClaudeArgsSet bool   `json:"-"`            // tracks runtime overrides, including an explicit empty --claude-args=
	TaskModel     string `json:"task_model"`   // model[:effort] spec for task execution (e.g., "opus", "opus:high", ":medium")
	ReviewModel   string `json:"review_model"` // model[:effort] spec for review phases (falls back to TaskModel)

	CodexEnabled         bool   `json:"codex_enabled"`
	CodexEnabledSet      bool   `json:"-"` // tracks if codex_enabled was explicitly set in config
	CodexCommand         string `json:"codex_command"`
	CodexModel           string `json:"codex_model"`
	CodexReasoningEffort string `json:"codex_reasoning_effort"`
	CodexTimeoutMs       int    `json:"codex_timeout_ms"`
	CodexTimeoutMsSet    bool   `json:"-"` // tracks if codex_timeout_ms was explicitly set in config
	CodexSandbox         string `json:"codex_sandbox"`
	CodexSandboxSet      bool   `json:"-"` // tracks if codex_sandbox was explicitly set outside embedded defaults

	ExternalReviewTool    string `json:"external_review_tool"` // "codex", "custom", or "none"
	ExternalReviewToolSet bool   `json:"-"`                    // tracks if external_review_tool was explicitly set in user config (not embedded default)
	CustomReviewScript    string `json:"custom_review_script"` // path to custom review script

	IterationDelayMs      int  `json:"iteration_delay_ms"`
	IterationDelayMsSet   bool `json:"-"` // tracks if iteration_delay_ms was explicitly set in config
	TaskRetryCount        int  `json:"task_retry_count"`
	TaskRetryCountSet     bool `json:"-"` // tracks if task_retry_count was explicitly set in config
	MaxIterations         int  `json:"max_iterations"`
	MaxIterationsSet      bool `json:"-"` // tracks if max_iterations was explicitly set in config
	MaxExternalIterations int  `json:"max_external_iterations"`
	ReviewPatience        int  `json:"review_patience"`

	FinalizeEnabled    bool `json:"finalize_enabled"`
	FinalizeEnabledSet bool `json:"-"` // tracks if finalize_enabled was explicitly set in config

	PreserveAnthropicAPIKey bool `json:"preserve_anthropic_api_key"` // when true, ANTHROPIC_API_KEY is passed through to the claude child process

	Executor     string `json:"executor"`       // "" (= claude, default) or ExecutorCodex
	PassClaudeMd bool   `json:"pass_claude_md"` // when true, codex reads project CLAUDE.md via project_doc_fallback_filenames; user-level ~/.claude/CLAUDE.md is not auto-passed (a one-time setup hint is printed)

	MovePlanOnCompletion bool `json:"move_plan_on_completion"`

	WorktreeEnabled    bool `json:"worktree_enabled"`
	WorktreeEnabledSet bool `json:"-"` // tracks if use_worktree was explicitly set in config

	PlansDir      string   `json:"plans_dir"`
	WatchDirs     []string `json:"watch_dirs"`     // directories to watch for progress files
	DefaultBranch string   `json:"default_branch"` // override auto-detected default branch
	VcsCommand    string   `json:"vcs_command"`    // custom VCS command (default: "git")
	CommitTrailer string   `json:"commit_trailer"` // trailer line to append to all commits

	// error patterns to detect in executor output (e.g., rate limit messages)
	ClaudeErrorPatterns []string `json:"claude_error_patterns"`
	CodexErrorPatterns  []string `json:"codex_error_patterns"`

	// limit patterns for wait+retry behavior (overlap with error patterns is intentional)
	ClaudeLimitPatterns []string      `json:"claude_limit_patterns"`
	CodexLimitPatterns  []string      `json:"codex_limit_patterns"`
	WaitOnLimit         time.Duration `json:"wait_on_limit"`
	WaitOnLimitSet      bool          `json:"-"` // tracks if wait_on_limit was explicitly set in config

	// session timeout for configured executor sessions (external review in Claude mode is excluded)
	SessionTimeout    time.Duration `json:"session_timeout"`
	SessionTimeoutSet bool          `json:"-"` // tracks if session_timeout was explicitly set in config

	// idle timeout for claude and codex executor sessions
	IdleTimeout    time.Duration `json:"idle_timeout"`
	IdleTimeoutSet bool          `json:"-"` // tracks if idle_timeout was explicitly set in config

	// notification parameters
	NotifyParams notify.Params `json:"-"`

	// output colors (RGB values as comma-separated strings)
	Colors ColorConfig `json:"-"`

	// prompts (loaded separately from files)
	TaskPrompt         string `json:"-"`
	ReviewFirstPrompt  string `json:"-"`
	ReviewSecondPrompt string `json:"-"`
	CodexPrompt        string `json:"-"`
	MakePlanPrompt     string `json:"-"`
	FinalizePrompt     string `json:"-"`
	CustomReviewPrompt string `json:"-"`
	CustomEvalPrompt   string `json:"-"`
	CodexReviewPrompt  string `json:"-"`

	// custom agents (loaded separately from files)
	CustomAgents []CustomAgent `json:"-"`
	// contains filtered or unexported fields
}

Config holds all configuration settings for ralphex. Fields ending in *Set track whether that field was explicitly set in config. This allows distinguishing explicit false/0 from "not set", enabling proper merge behavior where local config can override global config with zero values.

*Set fields:

  • ClaudeArgsSet: tracks if claude_args was explicitly overridden at runtime
  • CodexEnabledSet: tracks if codex_enabled was explicitly set
  • CodexTimeoutMsSet: tracks if codex_timeout_ms was explicitly set
  • CodexSandboxSet: tracks if codex_sandbox was explicitly set outside embedded defaults
  • IterationDelayMsSet: tracks if iteration_delay_ms was explicitly set
  • TaskRetryCountSet: tracks if task_retry_count was explicitly set
  • FinalizeEnabledSet: tracks if finalize_enabled was explicitly set
  • WorktreeEnabledSet: tracks if use_worktree was explicitly set
  • MaxIterationsSet: tracks if max_iterations was explicitly set
  • WaitOnLimitSet: tracks if wait_on_limit was explicitly set
  • SessionTimeoutSet: tracks if session_timeout was explicitly set

func Load

func Load(configDir string) (*Config, error)

Load loads all configuration from the specified directory. If configDir is empty, uses the default location (~/.config/ralphex/). It also auto-detects .ralphex/ in the current working directory for local overrides. It installs defaults if needed, parses config file, loads prompts and agents.

func LoadReadOnly added in v0.6.0

func LoadReadOnly(configDir string) (*Config, error)

LoadReadOnly loads configuration without installing defaults. use this in tests or tools that should not modify user's config directory. if config files don't exist, embedded defaults are used.

func (*Config) CodexExecutorSandbox added in v1.3.0

func (c *Config) CodexExecutorSandbox() string

CodexExecutorSandbox returns the sandbox mode to use when codex is the active executor (--codex mode). Defaults to "danger-full-access" because the codex executor needs to write git metadata and commit; an explicit codex_sandbox in user config wins. Distinct from the raw CodexSandbox field, which is what the external-review codex (claude mode) reads directly.

func (*Config) LocalDir added in v0.3.0

func (c *Config) LocalDir() string

LocalDir returns the local project config directory if one was detected. returns empty string if no local config was used.

type CustomAgent

type CustomAgent struct {
	Name    string // filename without extension
	Prompt  string // contents of the agent file (body after options header)
	Options        // embedded: model and agent type parsed from frontmatter
}

CustomAgent represents a user-defined review agent.

type Options added in v0.10.0

type Options struct {
	Model     string `yaml:"model"`
	AgentType string `yaml:"agent"`
}

Options holds agent options parsed from YAML frontmatter in agent files.

func (Options) String added in v0.10.0

func (o Options) String() string

String returns a human-readable summary of the options for logging.

func (Options) Validate added in v0.10.0

func (o Options) Validate() []string

Validate returns warnings for invalid option values. called after parseOptions which normalizes model to keyword form.

type Prompts added in v0.3.0

type Prompts struct {
	Task         string
	ReviewFirst  string
	ReviewSecond string
	Codex        string
	MakePlan     string
	Finalize     string
	CustomReview string
	CustomEval   string
	CodexReview  string
}

Prompts holds all loaded prompt templates for different phases of execution. Each prompt can be customized by placing a .txt file in the prompts directory.

type ResetResult added in v0.5.0

type ResetResult struct {
	ConfigReset  bool
	PromptsReset bool
	AgentsReset  bool
}

ResetResult holds the result of the reset operation.

func Reset added in v0.5.0

func Reset(configDir string, stdin io.Reader, stdout io.Writer) (ResetResult, error)

Reset interactively restores configuration files to embedded defaults. if configDir is empty, uses DefaultConfigDir().

type Values added in v0.3.0

type Values struct {
	ClaudeCommand              string
	ClaudeArgs                 string
	TaskModel                  string   // model for task execution (e.g., "opus", "sonnet", "haiku")
	ReviewModel                string   // model for review phases (falls back to TaskModel if empty)
	ClaudeErrorPatterns        []string // patterns to detect in claude output (e.g., rate limit messages)
	CodexEnabled               bool
	CodexEnabledSet            bool // tracks if codex_enabled was explicitly set
	CodexCommand               string
	CodexModel                 string
	CodexModelSet              bool // tracks if codex_model was explicitly set outside embedded defaults
	CodexReasoningEffort       string
	CodexReasoningEffortSet    bool // tracks if codex_reasoning_effort was explicitly set outside embedded defaults
	CodexTimeoutMs             int
	CodexTimeoutMsSet          bool // tracks if codex_timeout_ms was explicitly set
	CodexSandbox               string
	CodexSandboxSet            bool     // tracks if codex_sandbox was explicitly set outside embedded defaults
	CodexErrorPatterns         []string // patterns to detect in codex output (e.g., rate limit messages)
	ClaudeLimitPatterns        []string // patterns to detect rate limits in claude output (for wait+retry)
	CodexLimitPatterns         []string // patterns to detect rate limits in codex output (for wait+retry)
	WaitOnLimit                time.Duration
	WaitOnLimitSet             bool // tracks if wait_on_limit was explicitly set
	SessionTimeout             time.Duration
	SessionTimeoutSet          bool          // tracks if session_timeout was explicitly set
	IdleTimeout                time.Duration // kill session after no output for this duration
	IdleTimeoutSet             bool          // tracks if idle_timeout was explicitly set
	ExternalReviewTool         string        // "codex", "custom", or "none"
	ExternalReviewToolSet      bool          // tracks if external_review_tool was explicitly set in user config (not embedded default)
	CustomReviewScript         string        // path to custom review script (when ExternalReviewTool = "custom")
	IterationDelayMs           int
	IterationDelayMsSet        bool // tracks if iteration_delay_ms was explicitly set
	TaskRetryCount             int
	TaskRetryCountSet          bool // tracks if task_retry_count was explicitly set
	MaxIterations              int
	MaxIterationsSet           bool // tracks if max_iterations was explicitly set
	MaxExternalIterations      int  // override external review iteration limit (0 = auto)
	ReviewPatience             int  // terminate external review after N unchanged rounds (0 = disabled)
	FinalizeEnabled            bool
	FinalizeEnabledSet         bool // tracks if finalize_enabled was explicitly set
	PreserveAnthropicAPIKey    bool
	PreserveAnthropicAPIKeySet bool   // tracks if preserve_anthropic_api_key was explicitly set
	Executor                   string // "" (= claude, default) or "codex"
	ExecutorSet                bool   // tracks if executor was explicitly set
	PassClaudeMd               bool
	PassClaudeMdSet            bool // tracks if pass_claude_md was explicitly set
	MovePlanOnCompletion       bool
	MovePlanOnCompletionSet    bool // tracks if move_plan_on_completion was explicitly set
	WorktreeEnabled            bool
	WorktreeEnabledSet         bool   // tracks if use_worktree was explicitly set
	VcsCommand                 string // custom VCS command (default: "git")
	CommitTrailer              string // trailer line to append to all commits (e.g., "Co-authored-by: ...")
	PlansDir                   string
	DefaultBranch              string   // override auto-detected default branch
	WatchDirs                  []string // directories to watch for progress files

	// notification settings
	NotifyChannels        []string // channels to use: telegram, email, webhook, slack, custom
	NotifyChannelsSet     bool     // tracks if notify_channels was explicitly set (allows empty to disable)
	NotifyOnError         bool
	NotifyOnErrorSet      bool // tracks if notify_on_error was explicitly set
	NotifyOnComplete      bool
	NotifyOnCompleteSet   bool // tracks if notify_on_complete was explicitly set
	NotifyTimeoutMs       int
	NotifyTimeoutMsSet    bool // tracks if notify_timeout_ms was explicitly set
	NotifyTelegramToken   string
	NotifyTelegramChat    string
	NotifySlackToken      string
	NotifySlackChannel    string
	NotifySMTPHost        string
	NotifySMTPPort        int
	NotifySMTPPortSet     bool // tracks if notify_smtp_port was explicitly set
	NotifySMTPUsername    string
	NotifySMTPPassword    string
	NotifySMTPStartTLS    bool
	NotifySMTPStartTLSSet bool // tracks if notify_smtp_starttls was explicitly set
	NotifyEmailFrom       string
	NotifyEmailTo         []string // comma-separated in config
	NotifyEmailToSet      bool     // tracks if notify_email_to was explicitly set (allows empty to disable)
	NotifyWebhookURLs     []string // comma-separated in config
	NotifyWebhookURLsSet  bool     // tracks if notify_webhook_urls was explicitly set (allows empty to disable)
	NotifyCustomScript    string   // path to custom notification script (tilde-expanded)
}

Values holds scalar configuration values. Fields ending in *Set (e.g., CodexEnabledSet) track whether that field was explicitly set in config. This allows distinguishing explicit false/0 from "not set", enabling proper merge behavior where local config can override global config with zero values.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL