Settings in Prime Agent is a hierarchical schema defined by the Settings interface in settings-manager.ts, stored as JSON at global (<agentDir>/settings.json) and project (<cwd>/.prime-agent/settings.json) levels, covering provider defaults, compaction, retry logic, terminal rendering, image handling, MCP servers, and package loading. SettingsManager provides a file-backed storage abstraction (SettingsStorage) with lazy lock-only-on-write semantics, tracks dirty fields per session for selective flush, and supplies defaults for compaction (enabled, 16k reserve tokens), retry (3 max retries, 2s base delay), and terminal behavior (fullscreen mode, image display).
settings-manager.ts defines the Settings interface, which is the central configuration schema for prime-agent; its fields cover provider/model defaults, compaction, retry, terminal rendering, image handling, MCP servers, skill/extension loading, and more.[1] Global settings are stored at <agentDir>/settings.json and project settings at <cwd>/.prime-agent/settings.json, as established by FileSettingsStorage in settings-manager.ts.[1] FileSettingsStorage.withLock() only creates the settings directory and acquires the lock when a write is actually needed; reading a non-existent file returns undefined without touching the filesystem.[1]
The SettingsStorage interface exposes a single withLock(scope, fn) method; fn receives the current raw JSON string (or undefined if absent) and returns the new JSON string to write, or undefined to skip writing.[1] InMemorySettingsStorage provides a lock-free in-memory implementation of SettingsStorage, intended for tests that do not need file I/O.[1] SettingsManager tracks which global settings fields and nested subfields were modified during the current session using a modifiedFields: Set<keyof Settings> and modifiedNestedFields: Map<keyof Settings, Set<string>>, enabling selective dirty-flushing.[1]
recentModels in Settings stores at most 20 "provider/id" keys, most-recently-used first, controlled by RECENT_MODELS_LIMIT = 20 in settings-manager.ts.[1] DEFAULT_IDLE_EVICTION_MINUTES in settings-manager.ts is 90; this is the global daemon default for how long a session tree can be idle before the supervisor stops its worker process, overridable via idleEvictionMinutes in settings (or set to "off").[1] Settings.treeFilterMode controls which messages appear in the session tree; the default is "user-only", with other values being "default", "no-tools", "labeled-only", and "all".[1]
The CompactionSettings interface defaults: enabled to true, reserveTokens to 16384, keepRecentTokens to 20000, and agentCallable to true (which exposes the compact skill so the model can request compaction itself).[1] The AutoRefineSettings interface defaults: enabled to true, turnInterval to 25 assistant turns, compact to true, and cooldownMs to 20 minutes.[1] The BranchSummarySettings interface defaults skipPrompt to false (when true, the "Summarize branch?" prompt is skipped and no summary is produced by default) and reserveTokens to 16384.[1] Compaction reduces a session's token count by summarizing or pruning older messages to keep the session within a model's context window; without it, long sessions eventually exceed the limit and fail.
The RetrySettings interface defaults: enabled to true, maxRetries to 3, and baseDelayMs to 2000 (exponential backoff produces 2 s, 4 s, and 8 s delays); the nested ProviderRetrySettings.maxRetryDelayMs defaults to 60000 ms, which is the maximum server-requested delay before failing.[1]
The TerminalSettings interface defaults: showImages to true, clearOnShrink to false, showTerminalProgress to false, fullscreen to true (alternate-screen rendering), and fullscreenMouse to true (wheel scrolling; disable if it breaks text selection).[1] The ImageSettings interface defaults autoResize to true (images are resized to a 2000×2000 maximum for model compatibility) and blockImages to false; setting blockImages: true prevents all images from being sent to LLM providers.[1]
The PackageSource type allows either a plain string (load all resources from a package) or an object with a source field plus optional extensions, skills, prompts, and themes arrays to filter which resources are loaded.[1] Settings.npmCommand lets users override the npm command used for package lookup and install operations as an argv-style array (e.g. ["mise", "exec", "node@20", "--", "npm"]), which is useful for Cygwin or version-manager setups.[1] Settings.shellCommandPrefix is prepended to every bash command executed by the agent (e.g. "shopt -s expand_aliases" to enable alias support inside the kernel shell).[1]
Sources