Settings & Configurations

Relevant source files

The following files were used as context for generating this wiki page:

• src/features/settings/model/settings.ts
• src/features/settings/model/settings.test.ts
• src/features/settings/ui/SettingsView.test.ts
• src/features/orchestration/model/orchestrationPlan.ts
• src/features/automations/model/automationTemplates.ts
• src/features/pilots/model/pilotFiles.ts

Settings & Configurations manages application state, user preferences, and agent behaviors. It centralizes control over the workspace appearance, keyboard shortcuts, and agent orchestration parameters through a searchable, hierarchical interface.

The system partitions configuration into high-level groups containing specialized sections. This architecture ensures that diverse settings—from visual themes to complex automation triggers—remain discoverable and persistent across sessions.

Configuration Architecture

The application organizes settings into a three-tier hierarchy: Groups, Sections, and Entries. This structure facilitates logical grouping of related controls.

Hierarchical Organization

Groups act as primary buckets for navigation. Sections categorize specific functionalities within those groups, and Entries represent individual searchable controls.

Core Groups and Sections

Group	Section	Description
App	General	Build versions, notifications, and basic panel visibility.
App	Appearance	Themes, transparency, scale, and chat backgrounds.
App	Keybindings	Global and contextual keyboard shortcuts.
Agents	Providers	Account management for Claude, Codex, and other LLM harnesses.
Agents	Pilots	Resident agent behaviors and project associations.
Workspace	Worktrees	Management of git working copies and branches.
Sources: src/features/settings/model/settings.ts:40-155

Settings Search and Discovery

The search engine ranks results based on a scoring algorithm. It evaluates queries against entry labels, section descriptions, and hidden keywords.

Search Ranking Logic

The searchSettings function identifies matches using the following priority:

1. Label Start: Highest priority (Score 0) if the label begins with the query.
2. Label Inclusion: Medium priority (Score 1) if the label contains the query.
3. Keyword Inclusion: Lower priority (Score 2) if hidden keywords match.
4. Section Matches: Added to the list with a score offset of 0.5.

Persistence and State Management

The application persists configuration state primarily in localStorage. Cross-platform logic handles differences between macOS and Windows for specific features.

Storage Mechanics

• Flags: Boolean settings use readFlag and writeFlag helpers.
• Events: Changing critical settings (like NOTES_ENABLED or PILOTS_ENABLED) dispatches custom window events.
• Platform Specifics: Some settings, such as Close to tray, only exist on Windows, while Quick Composer defaults are tailored for macOS.

Persistence Lifecycle

Keybinding System

The keybinding module maps commands to keyboard chords. It prevents collision by validating new shortcuts against a catalog of default and custom bindings.

Shortcut Management

Users can override default bindings unless they are marked as fixed. The system normalizes chord strings (e.g., Shift+Command+K becomes Command+Shift+KeyK) to ensure consistency.

Field	Type	Description
command	string	Unique identifier for the action (e.g., App: Search).
keys	string	The keyboard chord representation.
when	string	The context required for the shortcut to activate.
fixed	boolean	If true, the shortcut cannot be changed by the user.
Sources: src/features/settings/model/settings.ts:612-680, src/features/settings/model/settings.test.ts:125-180

Collision Detection Flow

When a user attempts to record a shortcut, the system verifies availability:

1. Validates the chord is a standard shortcut format.
2. Checks the shortcutOwners map for existing assignments.
3. Rejects the change if another command currently owns the chord.
   Sources: src/features/settings/model/settings.ts:740-770

Specialized Configurations

Beyond general app settings, specific systems define their own configuration schemas.

Orchestration Settings

Orchestration manages how the lead agent delegates tasks to workers.

• Max Workers: Integer (1-4) limiting parallel processes.
• Choices: A catalog of available harness/model pairs.
  Sources: src/features/orchestration/model/orchestrationPlan.ts:13-20

Automation Triggers

Automations use schedule-based or event-based configurations.

• Time-based: Defines scheduleKind (weekly, weekdays) and execution time.
• Event-based: Triggers on external events like pull_request_opened or issue_opened.
  Sources: src/features/automations/model/automationTemplates.ts:32-48

Pilot Souls

Pilot configuration includes a SOUL.md file, which contains "Standing Instructions" that define the agent's identity and operational constraints.
Sources: src/features/pilots/model/pilotFiles.ts:13-25

Summary

The Settings & Configurations system provides a robust framework for managing the application's environment. By utilizing a hierarchical organization, a weighted search algorithm, and a centralized persistence model, it ensures that user preferences and agent behaviors are consistently applied across the workspace. Managing keybindings and specialized automation triggers further extends the customizability of the platform.