settings

Documentation

Index

• Variables
• func AddMarketplace(name string, source MarketplaceSource, scope Scope, projectPath string) error
• func AllMarketplaces(projectPath string) (map[string]ExtraMarketplace, error)
• func AtomicRename(tmpPath, finalPath string) error
• func LocalSettingsPath(projectPath string) (string, error)
• func ManagedSettingsPath() (string, error)
• func ProjectSettingsPath(projectPath string) (string, error)
• func RemoveMarketplace(name string, scope Scope, projectPath string) error
• func RemovePluginFromScope(fullName string, scope Scope, projectPath string) error
• func SaveSettings(s *Settings, scope Scope, projectPath string) error
• func ScopePath(scope Scope, projectPath string) (string, error)
• func SetPluginEnabled(fullName string, enabled bool, scope Scope, projectPath string) error
• func UserSettingsPath() (string, error)
• func WithLock(path string, fn func() error) error
• type ExtraMarketplace
• type FileLock
  • func NewFileLock(path string) *FileLock
  • func (l *FileLock) Lock() error
  • func (l *FileLock) Unlock() error
• type MarketplaceSource
• type PluginState
  • func FilterByScope(states []PluginState, scope Scope) []PluginState
  • func FilterDisabled(states []PluginState) []PluginState
  • func FilterEnabled(states []PluginState) []PluginState
  • func GetPluginState(pluginFullName string, projectPath string) (*PluginState, error)
  • func MergedPluginStates(projectPath string) ([]PluginState, error)
• type Scope
  • func AllScopes() []Scope
  • func ParseScope(s string) (Scope, error)
  • func WritableScopes() []Scope
  • func (s Scope) IsWritable() bool
  • func (s Scope) String() string
• type Settings
  • func LoadSettings(scope Scope, projectPath string) (*Settings, error)
  • func LoadSettingsFromPath(path string) (*Settings, error)
  • func NewSettings() *Settings
  • func (s *Settings) MarshalJSON() ([]byte, error)
  • func (s *Settings) UnmarshalJSON(data []byte) error

Variables

var (
	// ErrInvalidScope is returned when an unknown scope is provided
	ErrInvalidScope = errors.New("invalid scope: must be managed, user, project, or local")

	// ErrManagedReadOnly is returned when attempting to write to managed scope
	ErrManagedReadOnly = errors.New("managed scope is read-only")
)

Errors for the settings package

Functions

func AddMarketplace

func AddMarketplace(name string, source MarketplaceSource, scope Scope, projectPath string) error

AddMarketplace adds a marketplace to the specified scope

func AllMarketplaces

func AllMarketplaces(projectPath string) (map[string]ExtraMarketplace, error)

AllMarketplaces returns all extra marketplaces from all scopes merged Precedence order applies (higher precedence scope wins on conflicts)

func AtomicRename

func AtomicRename(tmpPath, finalPath string) error

AtomicRename performs an atomic rename with Windows fallback Exported for use by other packages (install.go, remove.go)

func LocalSettingsPath

func LocalSettingsPath(projectPath string) (string, error)

LocalSettingsPath returns the path to local settings.json

func ManagedSettingsPath

func ManagedSettingsPath() (string, error)

ManagedSettingsPath returns the path to managed settings.json

func ProjectSettingsPath

func ProjectSettingsPath(projectPath string) (string, error)

ProjectSettingsPath returns the path to project settings.json

func RemoveMarketplace

func RemoveMarketplace(name string, scope Scope, projectPath string) error

RemoveMarketplace removes a marketplace from the specified scope

func RemovePluginFromScope

func RemovePluginFromScope(fullName string, scope Scope, projectPath string) error

RemovePluginFromScope removes a plugin entry from a specific scope

func SaveSettings

func SaveSettings(s *Settings, scope Scope, projectPath string) error

SaveSettings saves settings to a specific scope Creates the necessary directories if they don't exist

func ScopePath

func ScopePath(scope Scope, projectPath string) (string, error)

ScopePath returns the settings.json path for a given scope For project/local scopes, projectPath must be provided

func SetPluginEnabled

func SetPluginEnabled(fullName string, enabled bool, scope Scope, projectPath string) error

SetPluginEnabled sets the enabled state for a plugin in the specified scope

func UserSettingsPath

func UserSettingsPath() (string, error)

UserSettingsPath returns the path to user settings.json

func WithLock

func WithLock(path string, fn func() error) error

WithLock executes a function while holding the lock

Types

type ExtraMarketplace

type ExtraMarketplace struct {
	Source MarketplaceSource `json:"source"`
}

ExtraMarketplace represents a marketplace entry in settings

type FileLock

type FileLock struct {
	// contains filtered or unexported fields
}

FileLock provides advisory file locking for concurrent access protection

func NewFileLock

func NewFileLock(path string) *FileLock

NewFileLock creates a new file lock for the given path The lock file will be created at path + ".lock"

func (*FileLock) Lock

func (l *FileLock) Lock() error

Lock acquires an exclusive lock, blocking until available or timeout

func (*FileLock) Unlock

func (l *FileLock) Unlock() error

Unlock releases the lock

type MarketplaceSource

type MarketplaceSource struct {
	Source string `json:"source"` // e.g., "github"
	Repo   string `json:"repo"`   // e.g., "owner/repo"
}

MarketplaceSource represents the source of a marketplace

type PluginState

type PluginState struct {
	FullName string // plugin@marketplace
	Enabled  bool
	Scope    Scope
}

PluginState represents the enabled/disabled state of a plugin with its scope

func FilterByScope

func FilterByScope(states []PluginState, scope Scope) []PluginState

FilterByScope returns plugin states filtered to a specific scope

func FilterDisabled

func FilterDisabled(states []PluginState) []PluginState

FilterDisabled returns only disabled plugin states

func FilterEnabled

func FilterEnabled(states []PluginState) []PluginState

FilterEnabled returns only enabled plugin states

func GetPluginState

func GetPluginState(pluginFullName string, projectPath string) (*PluginState, error)

GetPluginState returns the effective state for a specific plugin Returns the state from the highest precedence scope that has it

func MergedPluginStates

func MergedPluginStates(projectPath string) ([]PluginState, error)

MergedPluginStates loads all scopes and returns plugin states with scope information, respecting precedence order Precedence: Managed > Local > Project > User

type Scope

type Scope string

Scope represents a Claude Code settings scope

const (
	// ScopeManaged is the system-wide managed scope (read-only)
	// Location: /etc/claude-code/settings.json (Unix) or C:\ProgramData\ClaudeCode\settings.json (Windows)
	ScopeManaged Scope = "managed"

	// ScopeUser is the user-level scope
	// Location: ~/.claude/settings.json
	ScopeUser Scope = "user"

	// ScopeProject is the project-level scope (checked into git)
	// Location: <project>/.claude/settings.json
	ScopeProject Scope = "project"

	// ScopeLocal is the local project scope (gitignored)
	// Location: <project>/.claude/settings.local.json
	ScopeLocal Scope = "local"
)

func AllScopes

func AllScopes() []Scope

AllScopes returns all scopes in precedence order (highest to lowest)

func ParseScope

func ParseScope(s string) (Scope, error)

ParseScope parses a string into a Scope

func WritableScopes

func WritableScopes() []Scope

WritableScopes returns scopes that can be written to

func (Scope) IsWritable

func (s Scope) IsWritable() bool

IsWritable returns true if the scope can be written to

func (Scope) String

func (s Scope) String() string

String returns the string representation of the scope

type Settings

type Settings struct {
	// EnabledPlugins maps plugin@marketplace to enabled/disabled state
	EnabledPlugins map[string]bool `json:"enabledPlugins,omitempty"`

	// ExtraKnownMarketplaces stores additional marketplaces configured in this scope
	ExtraKnownMarketplaces map[string]ExtraMarketplace `json:"extraKnownMarketplaces,omitempty"`
	// contains filtered or unexported fields
}

Settings represents the Claude Code settings.json structure It preserves all unknown fields when reading/writing to avoid destroying user configuration that plum doesn't manage (e.g., permissions, hooks, model)

func LoadSettings

func LoadSettings(scope Scope, projectPath string) (*Settings, error)

LoadSettings loads settings from a specific scope Returns empty settings (not error) if file doesn't exist

func LoadSettingsFromPath

func LoadSettingsFromPath(path string) (*Settings, error)

LoadSettingsFromPath loads settings from a specific file path Returns empty settings (not error) if file doesn't exist

func NewSettings

func NewSettings() *Settings

NewSettings creates an empty Settings instance

func (*Settings) MarshalJSON

func (s *Settings) MarshalJSON() ([]byte, error)

MarshalJSON implements custom JSON marshaling to preserve unknown fields

func (*Settings) UnmarshalJSON

func (s *Settings) UnmarshalJSON(data []byte) error

UnmarshalJSON implements custom JSON unmarshaling to preserve unknown fields