config

Documentation

Overview

Package config loads TOML-based HUD configuration with defaults. LoadHud never returns nil and never returns an error — it fails open, using defaults whenever the config file is absent or unreadable.

Index

• Constants
• func Init() error
• func ResolveTheme(cfg *Config)
• type Config
  • func LoadHud() *Config
• type Line
  • func DefaultLines() []Line

Constants

const DefaultTemplate = `` /* 7132-byte string literal not displayed */

DefaultTemplate is the default config.toml content written by --init. It is valid TOML that LoadHud can parse without error.

Functions

func Init

func Init() error

Init writes the default config template and registers Claude Code hooks.

The config file is only written when it doesn't already exist, but hook registration runs unconditionally so that re-running --init can add hooks to an existing installation.

func ResolveTheme

func ResolveTheme(cfg *Config)

ResolveTheme populates cfg.ResolvedTheme by loading the named built-in theme and merging any custom [theme.overrides] on top of it. Called after the TOML decode so that both built-in selection and user overrides are captured. Also used by the preset package to trigger a palette refresh after mutating Style fields.

Types

type Config

type Config struct {
	Lines []Line `toml:"line"`
	Model struct {
		ShowContextSize bool `toml:"show_context_size"`
	} `toml:"model"`
	Context struct {
		BarWidth      int    `toml:"bar_width"`
		Display       string `toml:"display"`
		Value         string `toml:"value"`
		ShowBreakdown bool   `toml:"show_breakdown"`
	} `toml:"context"`
	Speed struct {
		WindowSecs int `toml:"window_secs"`
	} `toml:"speed"`
	Directory struct {
		Levels int    `toml:"levels"`
		Style  string `toml:"style"`
	} `toml:"directory"`
	Git struct {
		Dirty       bool `toml:"dirty"`
		AheadBehind bool `toml:"ahead_behind"`
		FileStats   bool `toml:"file_stats"`
	} `toml:"git"`
	Style struct {
		Separator  string `toml:"separator"`
		Icons      string `toml:"icons"`
		ColorLevel string `toml:"color_level"`
		Theme      string `toml:"theme"`
		// Mode controls the segment decoration style for all lines unless overridden per-line.
		// Accepted values: "plain" (default), "powerline", "minimal".
		Mode   string `toml:"mode"`
		Colors struct {
			Context  string `toml:"context"`
			Warning  string `toml:"warning"`
			Critical string `toml:"critical"`
		} `toml:"colors"`
	} `toml:"style"`
	Thresholds struct {
		// ContextWarning is the context usage percentage at which the widget
		// shifts to warning color. Default: 70.
		ContextWarning int `toml:"context_warning"`
		// ContextCritical is the context usage percentage at which the widget
		// shifts to critical color. Default: 85.
		ContextCritical int `toml:"context_critical"`
		// CostWarning is the session cost in USD at which the cost widget
		// shifts to warning color. Default: 5.00.
		CostWarning float64 `toml:"cost_warning"`
		// CostCritical is the session cost in USD at which the cost widget
		// shifts to critical color. Default: 10.00.
		CostCritical float64 `toml:"cost_critical"`
	} `toml:"thresholds"`

	// Theme holds the raw TOML overrides from [theme.overrides].
	// Each key is a widget name; the value has optional fg and bg fields.
	// After loading, ResolvedTheme is populated from Style.Theme + Theme.Overrides.
	Theme struct {
		Overrides map[string]theme.WidgetColors `toml:"overrides"`
	} `toml:"theme"`

	// Permission controls the permission-waiting widget.
	Permission struct {
		// ShowProject displays the project name of the waiting session next to the icon.
		// When false, only the icon is shown. Default: true.
		ShowProject bool `toml:"show_project"`
	} `toml:"permission"`

	// Usage controls the usage/rate-limit widget.
	Usage struct {
		// FiveHourThreshold is the minimum 5-hour usage percentage at which
		// the widget appears. Below this value the widget is hidden. Default: 0.
		FiveHourThreshold int `toml:"five_hour_threshold"`
		// SevenDayThreshold is the minimum 7-day usage percentage at which
		// the 7-day window is appended. Default: 80.
		SevenDayThreshold int `toml:"seven_day_threshold"`
		// CacheTTLSeconds overrides the success cache TTL. Default: 180.
		CacheTTLSeconds int `toml:"cache_ttl_seconds"`
	} `toml:"usage"`

	// Extra holds user-configured extra command settings. When Command is set,
	// the gather stage runs it and stores the result in RenderContext.ExtraOutput.
	Extra struct {
		Command string `toml:"command"`
	} `toml:"extra"`

	// ResolvedTheme is the effective per-widget color map after merging the
	// selected built-in theme with any custom [theme.overrides].
	// Populated by ResolveTheme() during LoadHud. Not read from TOML directly.
	ResolvedTheme theme.Theme `toml:"-"`
}

Config holds all HUD settings. Defaults are applied first; the TOML file overlays only the fields it explicitly sets.

func LoadHud

func LoadHud() *Config

LoadHud returns a Config with defaults overlaid by the TOML file at the XDG config location (or the legacy plugin path). It never returns nil and never returns an error — any failure to read or parse the config file results in the default config being returned.

type Line

type Line struct {
	Widgets []string `toml:"widgets"`
	Mode    string   `toml:"mode"`
}

Line represents a single rendered row in the statusline. Each widget name maps to a render function in the widget registry. Mode overrides the global style.mode for this specific line. Valid values: "" (inherit global), "plain", "powerline", "minimal".

func DefaultLines

func DefaultLines() []Line

DefaultLines returns the canonical default widget layout. It is defined here as the single source of truth and referenced by the "default" preset in the preset package. Returns a fresh slice each call so callers (including TOML decode) cannot mutate the canonical definition.