I replace role-specific high-contrast rules with one sRGB channel curve (1.3 contrast, mirrored pivots), preserving the palette's colored text and original filled-button ink. I keep Contrast Auto/On/Off, corrected light-palette surfaces and one shared active-toggle tint; the result was visually approved. I verified typechecking, 86 focused unit tests, 31 help checks across ten languages and focused browser regressions.
20 KiB
Settings and Preferences
Agent conventions
-
Appearance places Contrast at the inline end of the Mode row.
ui.settings.highContrastisauto(default),onoroff; Auto followsprefers-contrast: more. Initial bootstrap awaits the shared authoritative preferences load and applies the resolved palette and contrast before rendering. The control applies immediately, serializes writes independently of palette edits and reconciles failed writes through an authoritative read; its i reports Auto's current state and its error stays actionable. Every input sRGB channel usesc' = clamp(pivot + (c - pivot) * 1.3, 0, 1), with mirrored pivots0.5 - 0.3for dark palettes and0.5 + 0.3for light palettes. Filled-button ink is chosen against the original accent, keeping it stable when switching contrast. See PALETTE_SOURCES.md. -
openSettingsConfigFile(id)opens Configuration files and selects only an ID present in the editor's server catalogue. It sharesopenSettingsRow's short-lived same-origin hint with native Preferences on Electron and Tauri. A reopened editor preserves its dirty-discard confirmation; unavailable IDs preserve the current file. The editor consumes each target once and focuses its file selector. -
Settings → OpenCode's logging card opens
OpenCodeLogsActionin the common non-modalOutputWindow. Read once on explicit opening and on Refresh; closing, disposal and executable selection changes abort/fence the request. Global log snapshots stay in the mounted settings reader, separate from session state. Theswitch-to-infocommand/shortcut opens OpenCode settings and keeps existing key overrides. Version, executable, service actions and diagnostics share this global settings scope. -
Reuse
SettingsInfoTipfor contextual help withhelp={{ page: "opencode", anchor: "login-start" }}. Its short localizedtextremains the hover/focus tooltip; click, Enter or touch openshelpUrl(locale, page, anchor)throughopenExternalUrl, with a localized failure alert. The span's link role, cancelled label default and stopped activation events keep containing labels, disclosures and controls unchanged. Withouthelp, touch toggles the explanation.SettingsChoiceRow.helpand behavior-registryhelpcarry the same destination. Use only relevant published sections with matching explicit ids in every locale; dynamic diagnostics can remain tooltip-only, and actionable popovers keepSettingsInfoLinkorInfoPopoverButton. Destinations and gesture/native-opener behavior are covered bylib/help-url.test.tsandtests/browser/settings-info-tip.test.ts. -
General's Memory card owns the disabled-by-default
server.memoryEnabledswitch, About you/Project review, visit-stable New/Modified badges, revision-checked editing and confirmed Forget. Shared Preferences project resolution selects the authorized project memory, including its worktree; global memory belongs to the CodeNomad configuration. Flagged entries remain available for human review. Entry format, Git history, API, session instructions and badge frontiers are in AGENT_MEMORY.md. -
General's Memory Tidy up captures the current resolved Preferences project and memory scope and confirms before sending a fixed native intent to its exact local opener. The main renderer checks fresh memory availability/writability, creates a new session at that directory, activates it and sends the fixed cleanup prompt once. Embedded browser Settings use the same main-renderer action and close after a confirmed send. Preferences owns only the review and pending confirmation; context changes revoke unsent consent. See AGENT_MEMORY.md.
-
Settings → OpenCode's
OpenCodeLoginStartCard(stable row anchor#opencode-login-start) presents Launch at startup as one lone-setting switch with a one-sentence i tip saying it starts when the user session opens; the switch is its state. It readsGET /api/opencode/login-starton mount and reconnect (the latest request wins) and changes it withPOST, the switch disabled until the server answers. A refused change re-reads the state and shows one fixed, localized error under the row (failedorunsupported-binary); a failed read adds Try again;unavailabledisables the switch with a caption. Runtime, artifacts and stored supervision reconciliation are in OPENCODE_RUNTIME_SETUP.md. Browser regression:tests/browser/opencode-login-start.test.ts. -
General offers
autoExpandActiveSubsessions(default true): a new working/compacting/input chevron state opens visible branches belonging to the selected conversation, including its descendants at every depth (dev-docs/UI_SHELL.md). Disabling it leaves activity indicators and explicit navigation available; the preference is stored with the shared UI settings. -
General ends its behaviors card with
ui.settings.keepComputerAwake(default false), persisted through the UI config owner. Local native desktop windows and the native Preferences window show its title and an i tip. When enabled, the preference holds the existing native system-sleep lock in local application windows (including minimized windows) while allowing the display to turn off. Eligible working/compacting sessions hold the lock in local application windows and Electron remote windows. Remote windows ignore the preference; Tauri remote windows lack native wake-lock access. The Preferences window renders settings only and never requests a lock. Preference changes apply immediately. -
Settings → Providers separates Models, Web search and Images into three shared
.settings-disclosuregroups (no icons): Models starts open, Web search and Images folded, and a folded group mounts nothing, so its connection metadata, configuration contract and image-model catalog are read only once opened. Models and Web search each start with a provider selector, Connect action and configured-provider list; Web search then shows its global default and project override. Images (opencode/image-settings.ts,settings/image-settings-card.tsx,styles/components/image-settings.css) edits the Global document'sexperimental.image_generateandexperimental.media_blob. OpenCode readsimage_generateper field from the highest-priority document that sets it (unset means on, with the automatic model; onlyfalseturns the image tool off), butmedia_blob(likesubagent_depth) from the wholeexperimentalobject of the highest-priority document that has one, so writing a project block would hide inherited experimental settings. The document that decides each value is read from the native configuration entries and reported under its control when it is not the Global one. When the selected Location's own project document (the project write target) decidesmedia_blobthrough its existingexperimentalobject, the snapshot names it undermediaStorage.projectinstead, the box shows the effective value and saving also writesmedia_blobthere; the edit is refused if that object has disappeared, because creating one would hide inherited settings. The Missions depth editor's Inherit removes a project object left holding only thatmedia_blobwhen it equals the Global one (dev-docs/MISSIONS.md); Off is written asfalse, because removing the key would expose a lower-priority document that enables it. When the fresh Global write target has noexperimentalobject while a lower-priority document has one, creating it would hide that whole object (subagent depth, todos) from every Location without its own, even when the selected Location overrides it, so the group is read-only and the backend refuses the write; never copy the inherited values into the Global document instead. Each control appears only when the connected daemon'sConfig.InfoEncodeddeclares its key, because the nativeexperimentalobject rejects unknown keys; never write either key without that capability. Image models come from nativeGET /api/model?types=imagefor the selected Location. Reuse provider rows, selectors, inputs and action styles; do not add an API-key disclosure or a separate card design. Search-only integrations stay out of the Models group. Web search configuration lives entirely here. Read connection metadata while this Settings surface is visible, never credential secret values; keep API-key entry explicit and clear drafts on context changes. Use the authorized Global/Project document operations shared with plugin controls andopencode/native-setting-document.tsfor targeted JSONC edits. Preserve unrelated fields, native discovery roots, WSL atomic writes and conflict/connection/deletion fences. Group/search styling lives instyles/components/websearch-settings.css; credentials use native integration methods and remain global. -
Stats preferences explicitly aggregate the entire connected OpenCode service via
opencode/service-usage.ts. Reserve the Usage label for the provider subscription panel. Native project IDs span independent clones, so never label nativesession.statsas physical-folder/Git-family scoped. Keep connection/workspace fences,tools: "none"and periods bounded to 366 days; never load transcripts for statistics or imply billing/quota precision. Last snapshots and period choices restore through backend-ownedstate.ui.serviceUsage(eight each/1 MiB, validated service/channel/folder identity), never a Preferences writer to main-window client state or a workspace-UUID cache. Native aggregation must not await optional discovery/cache reads; cached responses cannot replace fresh data. Backend authorized admission order, not completion order or client time, chooses the period across windows; optional publication is bounded and shutdown-fenced. Keep last-known-owner totals explicitly stale through disconnect/errors and revoke them on verified owner/discovery changes. Read while mounted and document-visible; hide cancels queued/trailing demand, activation revalidates once and terminal hints use the shared activity cooldown. Never treat document visibility as native minimize/occlusion detection or equate blur with hidden. Seedev-docs/CACHE_REFRESH_CONVENTIONS.mdfor the remaining native scope. Styles live instyles/components/usage-dashboard.css. -
Settings rows keep only a title unless a caption is essential; secondary explanations go behind
components/settings/settings-info-tip.tsx(a focusable "i" with a hover/focus tooltip that a tap toggles on touch screens, a span so it never becomes a row label's control or toggles it), styled instyles/components/settings-info-tip.css. An explanation that must end with a link usessettings-info-link.tsxinstead: the same "i" as a button named by its text, opening a popover named by itstitle(click, Enter or Space; focus moves to the link; Escape or outside interaction closes it). Links to a setting useopenSettingsRow(section, row)(stores/settings-screen.ts) with the row's stableidanchor (such as#opencode-login-start), never its label, and the link's text is the setting's own title key so it follows any rename; the row (tabindex="-1") callsuseSettingsRowTarget(components/settings/settings-row-target.ts) to claim the target once, focus itself and stay in view while the cards above load, and the embedded Settings dialog skips its own initial focus while the shown section holds the targeted row (settingsRowPending); closing Settings drops an unclaimed target. Hosts carry only the section to a native Preferences window, so the row travels as a 15-second same-originlocalStoragehint that the window adopts for its active section on each request and onstorageevents (adoptSettingsRowHint). A link never reads or changes the linked setting. Behavior settings opt in withinfoKeyinstead ofsubtitleKey. Folded settings groups use the one.settings-disclosure(styles/components/settings-disclosure.css; a summary may hold an inline heading that keeps the summary's look): Missions gathers every agent/model choice under "Agents and models" with the current request in its summary, and Advanced ends with the environment-variable editor folded under a single title. -
SettingsServiceconfig reads (getOwner,getDoc) are a display cache that does not follow external edits. Config writes for every owner (mergePatchDoc,mergePatchOwner, andgetDoc's normalization) start from the document as it is on disk now (YamlDocStore.reloadAuthoritative), so a stale cache is never written back; an unreadable or invalidconfig.yamlrefuses the write withSettingsReadError(routes answer 503) instead of overwriting it. Access decisions never read the display cache: they use an authoritative read such asserverFlag(key)orreadEnvironmentForAdmission(). -
Server-owner settings that widen host-only access are listed in
settings/host-only-settings.ts: both config routes passhostOnlyServerCheck(isLocalRequest(request))to the write, which refuses with 403 a non-local write whose result changes one compared with the authoritative document it starts from (deleting the owner included), and their rows render only whilelocalRequest()is true. Settings → SideCars ends with such a lone-setting switch, Open SideCars over HTTPS (settings/sidecars-direct-https-card.tsx,server.sidecarsOverDirectHttps, i tip linking to the SideCar help); its admission rule is in REMOTE_CONTROL.md. Browser regression:tests/browser/host-only-controls.test.ts. -
Settings update/install actions (OpenCode and Info), OpenCode's post-update service restart, and Remote Control start/pairing-link actions use the shared
.selector-button-primaryaccent treatment. The sharedOpenCodeSetupPanelkeeps those same primary actions in startup recovery. Remote Control's header refresh is an icon-only.window-icon-button, retaining its localized accessible name, tooltip, disabled state and loading spinner. -
The native Preferences window never owns client state. Its General startup card (
settings/opener-startup-state-settings-card.tsx) targets the exact local window that opened Preferences: the host records that opener and an epoch (ElectronPreferencesWindowRegistry, TauriPreferencesWindow), forwards only the fixed commands inlib/native/startup-state-command.tsto that renderer, which runs them through its ownstores/client-statetransitions. Mutations carry the displayed epoch and degrade to a read after the opener changes. Startup state is per window: when the opener is unknown (Preferences restored at launch) or closed, the host adopts the most recently used local window as the opener (startupStateTargetId+adoptOpener/startup_state_target+set_opener), rotating the epoch so a change prepared for another window is only a read. The card re-reads a few times while the adopted window starts and stays disabled only when no local window can answer. -
The native Preferences window shows no session, so it never reacts to session events:
stores/sessions.tswires the session event handlers (errors, TUI toasts, permissions, session and worktree updates) only outside it. A session alert, toast or notice therefore appears in the windows showing sessions and is acknowledged once there (tests/browser/preferences-window.test.ts). -
Native Preferences resolves its project context through
settings/preferences-project-context.tsbefore Providers, Missions or Stats read project data. Backend workspace IDs are ephemeral: use the exact requested record while it exists; otherwise bind only one unambiguous exact-folder match from the backend's metadata-only inventory. Requests persist the opened backend-host folder asworkspacePath, separate from the selected nativelocation.directory(WSL/worktrees); keep the native directory for requests and drop any stale native workspace selector when rebinding. Requests without the backend folder match only their exact directory, never through guessed WSL translations or ancestors. A starting, missing or ambiguous project stays inactive. Read only on section demand, matching workspace lifecycle events or reconnect; never hydrate other workspaces, discover worktrees, create projects or poll. Record all deletion tombstones before filtering by the current binding so late inventory responses cannot publish deleted candidates, and revalidate when deletion resolves an ambiguity. Invalidation and newer native requests fence late reads, explicitly deleted occurrences never turn into sibling tabs, and rebinding persists through the existing Preferences request queue without resetting the section or newer scrolling. The shared renderer and request contract cover both Electron and Tauri; startup regressions live intests/browser/preferences-startup.test.ts. -
Settings → Info's Support CodeNomad card, between Updates and Diagnostics, holds one
.selector-button-secondaryaction that openshelpUrl(locale, "sponsor")throughopenExternalUrl, like theopen-sponsorpalette command and the native Help menu item; a failed opening shows the localizedcommands.openSponsor.failedalert in the card and is never replayed. Funding channels live only on the help site (docs/help/funding.json); never put payment links or amounts in the app. -
Settings → Info's Report a bug opens the
bug_report.ymlissue form with its text fields prefilled by id (BUG_REPORT_FIELDSinlib/bug-report.ts). When the template changes, keep those ids and their input/textarea types in sync:lib/bug-report.test.tschecks the repository's template. The section warms a bounded read of the form published on the default branch; the click never waits for it (WebKit drops user activation after about 1 s), using the settled assessment or else the form while a background read retries. Only a proven incompatible form (missing, unparsable, prefilled field removed or retyped) falls back to a blank issue carrying the same Markdown report; an unreachable read keeps the form. Never prefill listeners, addresses, paths, credentials or conversation data. -
Notification icon badges mirror the existing per-window bell/history unread count, never session status or native OS notification delivery. The browser favicon uses a dot; native Electron/Tauri hosts aggregate live primary-window counts and clear contributions on reload/close, keeping preferences and preview guests outside the badge authority. On Linux, Electron sends the badge to docks implementing the LauncherEntry API (Ubuntu Dock) for its
desktopName, which must stay the deb'sCodeNomad.desktop; the deb check enforces it. Keep UI projection inlib/notification-icon-badge.tsand host dispatch inlib/native/notification-badge.ts; do not add discovery scans or polling. -
Notifications have one routing table (
lib/notification-routing.ts): everyshowToastNotificationdeclares a category, and Settings → Notifications chooses per category On screen / History / System (components/settings/notification-routing-table.tsx,styles/components/notification-routing.css). The history, and therefore the icon badges, holds only what is routed there; errors always reach the screen and the history;transientlive feedback (progress, retry countdowns, "up to date") stays on screen only. The routing table is the only system-notification control: checking a System box requests permission, and savedosNotificationsEnabled,notifyOnNeedsInputandnotifyOnIdlepreferences only seed the routing until it is first saved. The bell (tab bar, or title bar in the macOS desktop app) is the history, independent of system notifications. System delivery is held back only while the window has focus (visible anddocument.hasFocus()), unless Notify when the app is focused (osNotificationsAllowWhenVisible) is on; a window left open behind another application or on another screen still notifies (tests/browser/system-notification-focus.test.ts). Classify new notifications by what the user would want to find later, not by their source file; a warning that must be seen once by default (the incomplete-recovery warning) uses a category that shows a bubble (projects), neverneedsInput, whose default is System only.