Documentation
¶
Overview ¶
Package settings provides a declarative, reflection-based settings system for Overkill, inspired by Warp's define_settings_group! macro.
Settings groups are Go structs with struct tags that describe each field's TOML key, default value, validation bounds, and UI metadata. The package provides runtime helpers for applying defaults, validating, and generating UI schemas — no code generation required (v1).
Struct tags:
setting:"key" — TOML key name default:"val" — default value (parsed to field type) desc:"help text" — human-readable description for UI min:"0" — minimum value (int/float only) max:"100" — maximum value (int/float only) required:"true" — must be non-zero
Example:
type AISettings struct {
Model string `setting:"model" default:"claude-sonnet-4-20250514" desc:"AI model"`
Temperature float64 `setting:"temperature" default:"0.7" min:"0" max:"2"`
MaxTokens int `setting:"max_tokens" default:"4096" min:"1" max:"200000"`
}
Register it with Register("ai", &AISettings{}), then call LoadAll(path) to populate from TOML, apply defaults, and validate.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ApplyDefaults ¶
ApplyDefaults sets zero-value fields on the struct to their default values as declared in struct tags. Recurses into nested structs.
func Register ¶
Register adds a named settings group to the default registry. ptr must be a pointer to a struct (e.g. &MySettings{}).
func ValidateStruct ¶
ValidateStruct checks all struct tags on the given pointer for constraint violations. Recurses into nested structs. Returns nil if everything is valid.
Types ¶
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds all registered settings groups.
func (*Registry) LoadAll ¶
LoadAll reads a TOML file (or a directory containing settings.toml), applies defaults, and validates all registered groups. The TOML file should have top-level keys matching group keys.
type SettingUI ¶
type SettingUI struct {
Name string `json:"name"`
Key string `json:"key"`
Type string `json:"type"` // "string", "bool", "int", "float"
Default string `json:"default"`
Description string `json:"description"`
Min string `json:"min,omitempty"`
Max string `json:"max,omitempty"`
Required bool `json:"required"`
}
SettingUI is the metadata for a single setting, used by the settings UI.
type ThinkingSettings ¶
type ThinkingSettings struct {
// Level controls how much internal reasoning the model exposes.
// Supported values: off, minimal, low, medium, high, x-high.
Level string `setting:"level" default:"off" desc:"Extended thinking budget for the model"`
}
ThinkingSettings defines the UI-editable thinking level configuration. Registered with the settings registry so the TUI settings pane can display it without hardcoding field names.
Source Files