Skip to content

configuration.md

Latest commit

 

History

History
126 lines (89 loc) · 3.48 KB

configuration.md

File metadata and controls

126 lines (89 loc) · 3.48 KB
Raw

Spurwechsel Configuration

Config File

Default path:

  • ~/.spurwechsel/config.yaml

Override path:

  • SPURWECHSEL_CONFIG_PATH

Loader entry point: spurwechsel/State/ProjectConfigStore.swift.

Managed Companion File

Spurwechsel manages a sibling AGENTS.md next to config.yaml.

  • default: ~/.spurwechsel/AGENTS.md
  • with override: sibling of SPURWECHSEL_CONFIG_PATH

AGENTS.md contains concise instructions for AI agents on what they may configure in config.yaml. File is app-owned and rewritten when missing or stale (for example after app updates or config saves).

Config Domains

  • version
  • codeServer
  • sections
  • projects
  • agents
  • shortcuts
  • terminal
  • theme

Raw file models live in spurwechsel/Models/ConfigFileModels.swift. Resolved runtime models live in spurwechsel/Models/ConfigModels.swift.

Resolution Pipeline

  1. Read YAML.
  2. Decode into UserConfigFile.
  3. Normalize paths and explicit values.
  4. Resolve defaults and validate each domain.
  5. Return ConfigLoadResult with diagnostics.

Resolver lives in spurwechsel/State/ConfigResolver.swift.

Project Records

Each project record stores:

  • path
  • optional name
  • optional sections (list of section ids)

Important detail: config stores repo roots only. Worktrees are discovered from git state, not persisted as separate records.

If project has no valid section assignments, UI places it into fallback section other.

Section Records

Each section record stores:

  • id (required)
  • optional name

projects[].sections must reference existing section ids. Section id other is reserved for fallback grouping and cannot be configured directly.

Agent Records

Each agent record stores:

  • name
  • command
  • optional default

If no valid agents remain after filtering, app falls back to built-ins:

  • opencode
  • claude
  • codex

Shortcut Records

Each shortcut stores:

  • command
  • key
  • modifiers

command accepts any command ID from command registry (toggle-command-bar, create-agent, toggle-voice-input, open-vscode-view, etc).

Resolver enforces one binding per command and removes signature collisions.

Terminal Records

Terminal config stores:

  • swapCommandAndControlWhenFocused

When enabled, Spurwechsel swaps command and control only for focused terminal input, including agent terminals. App shortcuts still win first, so configured bindings like ⌘K keep triggering app commands instead of sending swapped input into terminal.

Embedded terminals also import a curated subset of Ghostty user config from default Ghostty paths (if present), with later files overriding earlier ones and config-file includes resolved in Ghostty order. Supported imported keys:

  • font-family
  • font-size
  • font-thicken
  • font-thicken-strength
  • cursor-style
  • cursor-style-blink
  • cursor-opacity
  • selection-clear-on-copy
  • selection-clear-on-typing
  • selection-word-chars
  • mouse-hide-while-typing
  • mouse-scroll-multiplier
  • copy-on-select
  • scrollback-limit

Non-curated keys are ignored for Spurwechsel’s embedded terminal runtime.

Theme Records

Theme config may override any subset of light or dark palette tokens. Missing values inherit from defaults.

Diagnostics

Invalid config does not crash app. It produces banner-visible diagnostics and continues with fallback values.

Common causes:

  • bad YAML
  • missing required project or agent fields
  • invalid shortcut command or modifier
  • invalid codeServer.port
  • invalid theme token values