config

Documentation

Overview

Package config loads and validates Shepherd configuration.

It is the only package that reads config files or SHEPHERD_* environment variables; the resulting Config is passed explicitly to the rest of the app (no globals). Precedence, low to high: built-in defaults, then the .shepherd.yaml file, then SHEPHERD_* env vars (with __ marking nesting), then any overrides the CLI applies imperatively.

Index

• Variables
• type BitbucketConfig
• type ClaudeConfig
• type ClaudeHeadlessConfig
• type Config
  • func DefaultConfig() Config
  • func Load(explicitPath string) (Config, error)
  • func (c Config) Marshal() ([]byte, error)
  • func (c Config) Validate() error
• type ForgeConfig
• type GitHubConfig
• type LoggingConfig
• type NativeSessionConfig
• type NotificationsConfig
• type SessionConfig
• type TmuxSessionConfig
• type ValidationConfig
• type ValidationStep
• type WebhookConfig
• type WorktreesConfig

Variables

var DefaultConfigYAML string

DefaultConfigYAML is the commented .shepherd.yaml template written verbatim by `shepherd init`.

var SkillTemplate string

SkillTemplate is the Claude Code skill written to skills/shepherd/SKILL.md by `shepherd init`.

Types

type BitbucketConfig

type BitbucketConfig struct {
	BaseURL          string   `koanf:"base_url" yaml:"base_url"`
	Workspace        string   `koanf:"workspace" yaml:"workspace"`
	RepoSlug         string   `koanf:"repo_slug" yaml:"repo_slug"`
	EmailEnv         string   `koanf:"email_env" yaml:"email_env"`
	TokenEnv         string   `koanf:"token_env" yaml:"token_env"`
	DefaultReviewers []string `koanf:"default_reviewers" yaml:"default_reviewers"`
}

type ClaudeConfig

type ClaudeConfig struct {
	Binary                     string               `koanf:"binary" yaml:"binary"`
	Model                      string               `koanf:"model" yaml:"model"`
	FallbackModel              string               `koanf:"fallback_model" yaml:"fallback_model"`
	PermissionMode             string               `koanf:"permission_mode" yaml:"permission_mode"`
	DangerouslySkipPermissions bool                 `koanf:"dangerously_skip_permissions" yaml:"dangerously_skip_permissions"`
	Effort                     string               `koanf:"effort" yaml:"effort"`
	AddDirs                    []string             `koanf:"add_dirs" yaml:"add_dirs"`
	AppendSystemPrompt         string               `koanf:"append_system_prompt" yaml:"append_system_prompt"`
	AllowedTools               []string             `koanf:"allowed_tools" yaml:"allowed_tools"`
	DisallowedTools            []string             `koanf:"disallowed_tools" yaml:"disallowed_tools"`
	Headless                   ClaudeHeadlessConfig `koanf:"headless" yaml:"headless"`
	ExtraArgs                  []string             `koanf:"extra_args" yaml:"extra_args"`
}

type ClaudeHeadlessConfig

type ClaudeHeadlessConfig struct {
	OutputFormat   string  `koanf:"output_format" yaml:"output_format"` // text|json|stream-json
	MaxBudgetUSD   float64 `koanf:"max_budget_usd" yaml:"max_budget_usd"`
	TimeoutSeconds int     `koanf:"timeout_seconds" yaml:"timeout_seconds"`
}

type Config

type Config struct {
	Version       int                 `koanf:"version" yaml:"version"`
	Worktrees     WorktreesConfig     `koanf:"worktrees" yaml:"worktrees"`
	Forge         ForgeConfig         `koanf:"forge" yaml:"forge"`
	Session       SessionConfig       `koanf:"session" yaml:"session"`
	Claude        ClaudeConfig        `koanf:"claude" yaml:"claude"`
	Validation    ValidationConfig    `koanf:"validation" yaml:"validation"`
	Notifications NotificationsConfig `koanf:"notifications" yaml:"notifications"`
	Logging       LoggingConfig       `koanf:"logging" yaml:"logging"`

	// SourcePath is the file this config was loaded from ("" if pure defaults).
	// Not serialized; set by Load so commands can report provenance.
	SourcePath string `koanf:"-" yaml:"-"`
}

Config is the fully-resolved Shepherd configuration.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns the built-in baseline configuration. The .shepherd.yaml file and SHEPHERD_* env vars are overlaid on top of this. The default validation steps assume a Go project; users tailor them per repo via `init`.

func Load

func Load(explicitPath string) (Config, error)

Load resolves defaults, then the config file (explicitPath or auto-discovered), then SHEPHERD_* env vars, into a validated Config. An explicitPath that does not exist is an error; auto-discovery silently falls back to defaults+env.

func (Config) Marshal

func (c Config) Marshal() ([]byte, error)

Marshal renders the config as YAML (for provenance/debugging).

func (Config) Validate

func (c Config) Validate() error

Validate enforces enum and relationship invariants, returning all problems at once (wrapped as ErrInvalidInput).

type ForgeConfig

type ForgeConfig struct {
	Provider  string          `koanf:"provider" yaml:"provider"` // github | bitbucket
	GitHub    GitHubConfig    `koanf:"github" yaml:"github"`
	Bitbucket BitbucketConfig `koanf:"bitbucket" yaml:"bitbucket"`
}

type GitHubConfig

type GitHubConfig struct {
	Host             string   `koanf:"host" yaml:"host"`
	DefaultReviewers []string `koanf:"default_reviewers" yaml:"default_reviewers"`
	DraftPRs         bool     `koanf:"draft_prs" yaml:"draft_prs"`
}

type LoggingConfig

type LoggingConfig struct {
	Level  string `koanf:"level" yaml:"level"`   // debug|info|warn|error
	Format string `koanf:"format" yaml:"format"` // console|json
	File   string `koanf:"file" yaml:"file"`
}

type NativeSessionConfig

type NativeSessionConfig struct {
	LogDir string `koanf:"log_dir" yaml:"log_dir"`
	Detach bool   `koanf:"detach" yaml:"detach"`
}

type NotificationsConfig

type NotificationsConfig struct {
	Enabled  bool          `koanf:"enabled" yaml:"enabled"`
	OnEvents []string      `koanf:"on_events" yaml:"on_events"`
	Channels []string      `koanf:"channels" yaml:"channels"` // terminal | webhook | command
	Webhook  WebhookConfig `koanf:"webhook" yaml:"webhook"`
	Command  string        `koanf:"command" yaml:"command"`
}

type SessionConfig

type SessionConfig struct {
	Backend string              `koanf:"backend" yaml:"backend"` // auto | tmux | native
	Tmux    TmuxSessionConfig   `koanf:"tmux" yaml:"tmux"`
	Native  NativeSessionConfig `koanf:"native" yaml:"native"`
}

type TmuxSessionConfig

type TmuxSessionConfig struct {
	SocketName    string `koanf:"socket_name" yaml:"socket_name"`
	SessionPrefix string `koanf:"session_prefix" yaml:"session_prefix"`
	WSL           bool   `koanf:"wsl" yaml:"wsl"`
}

type ValidationConfig

type ValidationConfig struct {
	StopOnFailure  bool              `koanf:"stop_on_failure" yaml:"stop_on_failure"`
	DefaultTimeout string            `koanf:"default_timeout" yaml:"default_timeout"`
	Env            map[string]string `koanf:"env" yaml:"env,omitempty"`
	Steps          []ValidationStep  `koanf:"steps" yaml:"steps"`
}

type ValidationStep

type ValidationStep struct {
	Name            string `koanf:"name" yaml:"name"`
	Run             string `koanf:"run" yaml:"run"`
	Timeout         string `koanf:"timeout" yaml:"timeout,omitempty"`
	ContinueOnError bool   `koanf:"continue_on_error" yaml:"continue_on_error,omitempty"`
	WorkdirRel      string `koanf:"workdir" yaml:"workdir,omitempty"`
}

type WebhookConfig

type WebhookConfig struct {
	URLEnv string `koanf:"url_env" yaml:"url_env"`
	Format string `koanf:"format" yaml:"format"` // slack | json
}

type WorktreesConfig

type WorktreesConfig struct {
	Root         string `koanf:"root" yaml:"root"`
	NameTemplate string `koanf:"name_template" yaml:"name_template"`
	BranchPrefix string `koanf:"branch_prefix" yaml:"branch_prefix"`
	BaseBranch   string `koanf:"base_branch" yaml:"base_branch"`
	AutoCleanup  bool   `koanf:"auto_cleanup" yaml:"auto_cleanup"`
}