Documentation
¶
Overview ¶
Package config owns Loom's on-disk configuration, app state, profile catalog, and workspace registry.
The root config directory defaults to ~/.loom (overridable via $LOOM_HOME). WorkspaceContext carries the resolved directory for a given invocation and is threaded through the app rather than relying on globals, so per-workspace configs at <repo>/.loom/ can coexist with the global config. LoadConfigFrom/LoadStateFrom accept an empty path to mean "use the default directory."
MigrateLegacyHome performs the one-shot rename from ~/.claude-squad to ~/.loom that covers users upgrading across the rebrand; it is idempotent and safe to call on every startup.
Index ¶
- Constants
- Variables
- func AtomicWriteFile(path string, data []byte, perm os.FileMode) error
- func EnsureGitignore(repoPath string) error
- func GetClaudeCommand() (string, error)
- func GetConfigDir() (string, error)
- func GetGlobalConfigDir() (string, error)
- func MigrateLegacyHome() error
- func SaveConfigTo(config *Config, dir string) error
- func SaveState(state *State) error
- func SaveStateTo(state *State, dir string) error
- func SaveWorkspaceRegistry(reg *WorkspaceRegistry) error
- func WorkspaceConfigDir(ws *Workspace) string
- type AppState
- type Config
- func (c *Config) CacheTTL1hEnabled() bool
- func (c *Config) Effort() string
- func (c *Config) GetBranchPrefix() string
- func (c *Config) GetProfiles() []Profile
- func (c *Config) GetProgram() string
- func (c *Config) HeadroomProxyEnabled() bool
- func (c *Config) Model() string
- func (c *Config) Mutate(fn func(*Config))
- func (c *Config) PermissionMode() string
- func (c *Config) RemoteControlEnabled() bool
- type InstanceStorage
- type Profile
- type State
- type StateManager
- type Workspace
- type WorkspaceContext
- type WorkspaceRegistry
- func (r *WorkspaceRegistry) Add(name, repoPath string) error
- func (r *WorkspaceRegistry) FindByPath(path string) *Workspace
- func (r *WorkspaceRegistry) Get(name string) *Workspace
- func (r *WorkspaceRegistry) GetOpenWorkspaces() []Workspace
- func (r *WorkspaceRegistry) Remove(name string) error
- func (r *WorkspaceRegistry) Rename(oldName, newName string) error
- func (r *WorkspaceRegistry) SetOpenWorkspaces(names []string) error
- func (r *WorkspaceRegistry) UpdateLastUsed(name string) error
Constants ¶
const ( StateFileName = "state.json" InstancesFileName = "instances.json" )
StateFileName is the on-disk filename for ephemeral app state (help-screen-seen flags, etc.). InstancesFileName stores the serialized session list. Both are resolved relative to the config directory.
const (
ConfigFileName = "config.json"
)
ConfigFileName is the on-disk filename of the Loom user config, resolved relative to the config directory (LOOM_HOME or ~/.loom).
const (
EnvHome = "LOOM_HOME"
)
EnvHome names the override env var for the application's config directory. Legacy CLAUDE_SQUAD_HOME is honored as a deprecated fallback with a one-time warning so shell configs continue working across the rename from claude-squad to loom.
Variables ¶
var ClaudeEfforts = []string{"default", "low", "medium", "high", "xhigh", "max"}
ClaudeEfforts lists the --effort values the Claude Preferences and Session Launch Options screens cycle through, matching what `claude --help` documents for --effort.
var ClaudeModels = []string{"default", "sonnet", "opus", "haiku"}
ClaudeModels lists the --model aliases the Claude Preferences and Session Launch Options screens cycle through. Short aliases, not versioned IDs, so this list doesn't need updating when new Claude models ship.
var ClaudePermissionModes = []string{"default", "acceptEdits", "plan", "auto", "dontAsk", "bypassPermissions"}
ClaudePermissionModes lists the values --permission-mode accepts, in the order the Claude Preferences screen cycles through them.
Functions ¶
func AtomicWriteFile ¶
AtomicWriteFile writes data to path via a temp file in the same directory, fsyncs it, and renames it into place. This guarantees readers see either the old contents or the new contents, never a truncated or empty file.
The temp file is created with O_EXCL so concurrent writers don't share it. If the write or rename fails, the temp file is removed and the original file is left untouched.
After rename we also fsync the parent directory so the directory entry update is durable; without it a power loss between rename and the next filesystem commit can leave the old contents (or, on data=writeback mode, an empty file) visible after reboot. Best-effort — silently a no-op on filesystems/platforms (e.g. Windows) that don't support directory fsync.
func EnsureGitignore ¶
EnsureGitignore ensures .loom/ is listed in the repo's .gitignore. Writes atomically via AtomicWriteFile so a crash or a concurrent call can't leave a half-written entry behind. An O_APPEND-based write would issue two syscalls (newline fixup, then entry), and racing callers each saw an absent entry and each appended their own copy.
func GetClaudeCommand ¶
GetClaudeCommand attempts to find the "claude" command in the user's shell It checks in the following order: 1. Shell alias resolution: using "which" command 2. PATH lookup
If both fail, it returns an error.
func GetConfigDir ¶
GetConfigDir returns the path to the application's configuration directory. If LOOM_HOME is set, that value is used directly as the config directory. CLAUDE_SQUAD_HOME is honored as a deprecated fallback with a one-time warning. The value must be an absolute path (after ~ expansion). Falls back to ~/.loom otherwise.
func GetGlobalConfigDir ¶
GetGlobalConfigDir returns ~/.loom/ regardless of LOOM_HOME.
func MigrateLegacyHome ¶
func MigrateLegacyHome() error
MigrateLegacyHome performs a one-time rename of the legacy config directory (~/.claude-squad) to its new location (~/.loom) so that in-flight instances, worktrees, and scripts survive the rename.
Behavior:
- If ~/.loom already exists, return (idempotent; nothing to do).
- If ~/.claude-squad is absent, return (fresh install).
- Otherwise os.Rename the directory and print a one-line notice to stderr so the operator knows what happened.
When LOOM_HOME or CLAUDE_SQUAD_HOME is set (i.e. the user has overridden the default path), migration is skipped — the user has explicitly chosen a location and is assumed to have already placed their state there.
Errors from os.Rename (e.g. cross-device) are returned; the caller should fall through to normal startup on failure since the legacy dir is still readable and GetConfigDir will honor CLAUDE_SQUAD_HOME as a deprecated fallback if the user points at it explicitly.
func SaveConfigTo ¶
SaveConfigTo saves the configuration to an explicit directory.
func SaveStateTo ¶
SaveStateTo saves state to an explicit directory.
func SaveWorkspaceRegistry ¶
func SaveWorkspaceRegistry(reg *WorkspaceRegistry) error
SaveWorkspaceRegistry writes the workspace registry to the global config dir.
func WorkspaceConfigDir ¶
WorkspaceConfigDir returns the .loom directory inside the workspace repo.
Types ¶
type AppState ¶
type AppState interface {
// GetHelpScreensSeen returns the bitmask of seen help screens
GetHelpScreensSeen() uint32
// SetHelpScreensSeen updates the bitmask of seen help screens
SetHelpScreensSeen(seen uint32) error
}
AppState handles application-level state
type Config ¶
type Config struct {
// DefaultProgram is the default program to run in new instances
DefaultProgram string `json:"default_program"`
// DaemonPollInterval is retained for config.json backward compatibility
// only — its consumer (the background daemon) has been removed.
DaemonPollInterval int `json:"daemon_poll_interval"`
// BranchPrefix is the prefix used for git branches created by the application.
BranchPrefix string `json:"branch_prefix"`
// Profiles is a list of named program profiles.
Profiles []Profile `json:"profiles,omitempty"`
// ClaudeRemoteControl controls whether new Claude sessions launch
// with `--remote-control` (named after the session title). It is a
// pointer so a config file predating this field (nil) is treated as
// enabled rather than taking the bool zero value; only an explicit
// false disables it. Read it through RemoteControlEnabled.
ClaudeRemoteControl *bool `json:"claude_remote_control,omitempty"`
// ClaudePermissionMode is the --permission-mode value new Claude
// sessions launch with. Unlike ClaudeRemoteControl, DefaultConfig
// sets this explicitly to "default" rather than leaving it nil — nil
// only occurs for a config.json predating this field, and is
// treated identically to "default" (no flag injected; Claude's own
// default applies). Read it through PermissionMode.
ClaudePermissionMode *string `json:"claude_permission_mode,omitempty"`
// HeadroomProxy controls whether new Claude sessions launch with
// ANTHROPIC_BASE_URL pointed at Headroom's proxy (see
// session.HeadroomProxyEnv). A no-op for agents other than Claude.
// Loom does not start or manage the headroom proxy process itself —
// the user is expected to have it running separately. Defaults to
// off (DefaultConfig sets it explicitly to false) since it's
// opt-in. Mutually exclusive with ClaudeRemoteControl: enabling one
// disables the other, enforced in the Claude Preferences toggle
// handler, the Session Launch Options modal, and defensively again
// in applyLaunchOptions so a hand-edited config.json with both
// fields true still can't launch both at once. Read it through
// HeadroomProxyEnabled.
HeadroomProxy *bool `json:"headroom_proxy,omitempty"`
// ClaudeModel is the --model value new Claude sessions launch with.
// Values are short CLI aliases (not versioned IDs) so the list
// stays valid as new models ship without a code change. "default"
// is a no-op — Claude's own default applies. Read it through Model.
ClaudeModel *string `json:"claude_model,omitempty"`
// ClaudeEffort is the --effort value new Claude sessions launch
// with. "default" is a no-op — Claude's own default applies. Read
// it through Effort.
ClaudeEffort *string `json:"claude_effort,omitempty"`
// CacheTTL1h controls whether new Claude sessions launch with
// ENABLE_PROMPT_CACHING_1H=1 (see session.CacheTTL1hEnv), extending
// Claude's prompt cache from the default 5-minute TTL to 1 hour. A
// no-op for agents other than Claude. Defaults to off (DefaultConfig
// sets it explicitly to false) since it's opt-in. Read it through
// CacheTTL1hEnabled.
CacheTTL1h *bool `json:"cache_ttl_1h,omitempty"`
// contains filtered or unexported fields
}
Config represents the application configuration
func LoadConfig ¶
func LoadConfig() *Config
LoadConfig loads configuration from the default config directory. It is a convenience wrapper around LoadConfigFrom(""). If the config file does not yet exist, a default config is written to disk.
func LoadConfigFrom ¶
LoadConfigFrom loads configuration from an explicit directory. Empty `dir` is a soft shim: a warning is logged and the global config directory is used. Per docs/specs/workspaces.md §3 internal callers must pass a resolved WorkspaceContext.ConfigDir.
func LoadConfigFromGlobal ¶
func LoadConfigFromGlobal() *Config
LoadConfigFromGlobal loads configuration from the global (LOOM_HOME or ~/.loom) directory. Prefer this over LoadConfigFrom("") at call sites that truly want the global config — the explicit name prevents workspace-context leaks.
func (*Config) CacheTTL1hEnabled ¶ added in v0.6.0
CacheTTL1hEnabled reports whether new Claude sessions should launch with ENABLE_PROMPT_CACHING_1H=1. Defaults to false when unset.
func (*Config) Effort ¶ added in v0.6.0
Effort returns the configured --effort value, defaulting to "default" when unset. Unlocked for the same reason as PermissionMode/Model.
func (*Config) GetBranchPrefix ¶ added in v0.3.0
GetBranchPrefix returns BranchPrefix under a read lock. Use this instead of reading the field directly from any goroutine other than the one currently calling Mutate — in practice, scriptHost.BranchPrefix, which runs on the Lua dispatch goroutine.
func (*Config) GetProfiles ¶
GetProfiles returns a unified list of profiles. If Profiles is defined, those are returned with the default profile first. Otherwise, a single profile is synthesized from DefaultProgram.
func (*Config) GetProgram ¶
GetProgram returns the program to run. If Profiles is non-empty and DefaultProgram matches a profile name, that profile's Program is returned. Otherwise DefaultProgram is returned as-is.
func (*Config) HeadroomProxyEnabled ¶ added in v0.6.0
HeadroomProxyEnabled reports whether new Claude sessions should launch with ANTHROPIC_BASE_URL pointed at Headroom's proxy. Defaults to false when unset.
func (*Config) Model ¶ added in v0.5.0
Model returns the configured --model alias, defaulting to "default" when unset (nil). Unlocked for the same reason as PermissionMode.
func (*Config) Mutate ¶ added in v0.3.0
Mutate runs fn with the write lock held. Callers outside this package (the settings overlay) use this instead of writing exported fields directly, so a concurrent GetBranchPrefix cannot observe a torn write. fn must not call GetBranchPrefix or Mutate itself (would deadlock).
func (*Config) PermissionMode ¶ added in v0.4.0
PermissionMode returns the configured --permission-mode value, defaulting to "default" when unset (nil). Deliberately unlocked, like RemoteControlEnabled: it's read only from the main goroutine (view rendering, instance creation during key handling, and from inside a Mutate callback in the Claude Preferences cycle handler — a Mutate-held lock is not reentrant, so a locked accessor here would deadlock). If a future caller needs this from the Lua dispatch goroutine, add a locked variant rather than locking this one.
func (*Config) RemoteControlEnabled ¶ added in v0.3.0
RemoteControlEnabled reports whether new Claude sessions should launch with the --remote-control flag. Defaults to true when unset so the feature is on out of the box; only an explicit false disables it.
type InstanceStorage ¶
type InstanceStorage interface {
// SaveInstances saves the raw instance data
SaveInstances(instancesJSON json.RawMessage) error
// GetInstances returns the raw instance data
GetInstances() json.RawMessage
// DeleteAllInstances removes all stored instances
DeleteAllInstances() error
}
InstanceStorage handles instance-related operations
type Profile ¶
type Profile struct {
// Name is the short identifier shown in the profile picker. Must be
// unique within a Config's Profiles list.
Name string `json:"name"`
// Program is the literal command string run when this profile is
// selected (e.g. "aider --model gpt-4"). No templating is applied.
Program string `json:"program"`
}
Profile is a named shortcut for a program invocation. Profiles let users store multiple agent configurations (e.g. "aider-gpt4", "claude-fast") and pick between them at session creation or by setting DefaultProgram to a profile's Name.
type State ¶
type State struct {
// HelpScreensSeen is a bitmask tracking which help screens have been shown
HelpScreensSeen uint32 `json:"help_screens_seen"`
// Instances stores the serialized instance data as raw JSON
InstancesData json.RawMessage `json:"instances"`
// contains filtered or unexported fields
}
State represents the application state that persists between sessions
func LoadState ¶
func LoadState() *State
LoadState loads the state from disk. If it cannot be done, we return the default state.
func LoadStateFrom ¶
LoadStateFrom loads state from an explicit directory. Empty `dir` is a soft shim: a warning is logged and the global config directory is used. Internal callers must pass a resolved WorkspaceContext.ConfigDir per docs/specs/workspaces.md §3. The returned State remembers dir so that SaveState writes back to it.
func LoadStateFromGlobal ¶
func LoadStateFromGlobal() *State
LoadStateFromGlobal loads state from the global config directory. Prefer this over LoadStateFrom("") for call sites that truly want the global state file.
func (*State) DeleteAllInstances ¶
DeleteAllInstances removes all stored instances
func (*State) GetHelpScreensSeen ¶
GetHelpScreensSeen returns the bitmask of seen help screens
func (*State) GetInstances ¶
func (s *State) GetInstances() json.RawMessage
GetInstances returns the raw instance data
func (*State) SaveInstances ¶
func (s *State) SaveInstances(instancesJSON json.RawMessage) error
SaveInstances saves the raw instance data
func (*State) SetHelpScreensSeen ¶
SetHelpScreensSeen updates the bitmask of seen help screens
type StateManager ¶
type StateManager interface {
InstanceStorage
AppState
}
StateManager combines instance storage and app state management
type Workspace ¶
type Workspace struct {
Name string `json:"name"`
Path string `json:"path"`
AddedAt time.Time `json:"added_at"`
}
Workspace represents a registered workspace tied to a git repository.
type WorkspaceContext ¶
type WorkspaceContext struct {
// Name is the workspace name. Empty string means global.
Name string
// ConfigDir is the absolute path to the config directory
// (e.g., /repo/.loom or ~/.loom).
ConfigDir string
// RepoPath is the absolute path to the repo root. Empty for global.
RepoPath string
}
WorkspaceContext carries the resolved identity of the active workspace. A nil *WorkspaceContext means "global" (no workspace).
func GlobalWorkspaceContext ¶
func GlobalWorkspaceContext() (*WorkspaceContext, error)
GlobalWorkspaceContext returns a WorkspaceContext pointing at ~/.loom.
func ResolveWorkspace ¶
func ResolveWorkspace(cwd string, registry *WorkspaceRegistry) (*WorkspaceContext, error)
ResolveWorkspace determines the workspace context for the given working directory. If a registered workspace matches, returns its context. Otherwise returns the global context.
func WorkspaceContextFor ¶
func WorkspaceContextFor(ws *Workspace) *WorkspaceContext
WorkspaceContextFor returns a WorkspaceContext for the given workspace.
type WorkspaceRegistry ¶
type WorkspaceRegistry struct {
Workspaces []Workspace `json:"workspaces"`
LastUsed string `json:"last_used"`
OpenWorkspaces []string `json:"open_workspaces,omitempty"`
}
WorkspaceRegistry holds all registered workspaces, tracks the last-focused one, and records the ordered list of open workspace tabs for restore.
func LoadWorkspaceRegistry ¶
func LoadWorkspaceRegistry() (*WorkspaceRegistry, error)
LoadWorkspaceRegistry reads the workspace registry from the global config dir. Returns an empty registry if the file doesn't exist.
func (*WorkspaceRegistry) Add ¶
func (r *WorkspaceRegistry) Add(name, repoPath string) error
Add registers a new workspace. Validates uniqueness of name and that the path is a git repository. Automatically calls EnsureGitignore.
func (*WorkspaceRegistry) FindByPath ¶
func (r *WorkspaceRegistry) FindByPath(path string) *Workspace
FindByPath finds a workspace whose Path matches or is a parent of the given path.
func (*WorkspaceRegistry) Get ¶
func (r *WorkspaceRegistry) Get(name string) *Workspace
Get finds a workspace by name.
func (*WorkspaceRegistry) GetOpenWorkspaces ¶
func (r *WorkspaceRegistry) GetOpenWorkspaces() []Workspace
GetOpenWorkspaces returns the workspaces named in OpenWorkspaces, in order. Names that no longer exist in the registry are skipped silently.
func (*WorkspaceRegistry) Remove ¶
func (r *WorkspaceRegistry) Remove(name string) error
Remove removes a workspace by name. Does NOT delete the .loom/ directory.
func (*WorkspaceRegistry) Rename ¶
func (r *WorkspaceRegistry) Rename(oldName, newName string) error
Rename changes a workspace's name. Updates LastUsed if it pointed to the old name.
func (*WorkspaceRegistry) SetOpenWorkspaces ¶
func (r *WorkspaceRegistry) SetOpenWorkspaces(names []string) error
SetOpenWorkspaces replaces the ordered list of open workspace names and persists the registry. Unknown names are silently dropped so the stored list always references workspaces that still exist.
The on-disk registry is reloaded before save so concurrent writers (a `loom workspace add` invocation in another shell, or a second running TUI) are not clobbered by this process's stale snapshot of Workspaces. The receiver's in-memory state is refreshed to match the merged result.
func (*WorkspaceRegistry) UpdateLastUsed ¶
func (r *WorkspaceRegistry) UpdateLastUsed(name string) error
UpdateLastUsed sets the last used workspace and saves the registry. Returns an error if no workspace with the given name exists.
The on-disk registry is reloaded before save so concurrent writers (a `loom workspace add` invocation in another shell, or a second running TUI) are not clobbered by this process's stale snapshot of Workspaces. The receiver's in-memory state is refreshed to match the merged result.