← Docs

Settings

Settings configures Brisal’s look and available providers, models, and agents. This page explains the shape: how to access it and the two-tier scope model that keeps everything predictable. Individual toggles are documented on their respective concept pages.

How to reach Settings

Access Settings via the gear icon in the header, which opens a menu with four options:

DestinationPurpose
SettingsPer-workspace tabs: Appearance (mode, font, palette), Hotkeys (keyboard shortcuts), Git (commit authoring)
WorkspacesCreate, select, archive, delete workspaces
SkillsGlobal skills settings, mainly the opt-in for external skills from ~/.agents/skills
SystemMachine-wide read-only models catalog (providers/agents use the same copy model but are browsed in workspace tabs)

The gear menu jumps directly to these areas. Appearance and Hotkeys share the Settings screen because they use the merge model. Git is also per-workspace, with no system tier — commit identity lives in the workspace itself. The same Git editor appears on each workspace’s own Git tab.

Two tiers: system and workspace

Configuration lives in one of two tiers:

  • System — machine-wide defaults and built-in catalog that all workspaces inherit
  • Workspace — per-workspace layer where you customize. Each workspace is isolated; changes stay contained.

These tiers exist for compartmentalization: each client’s providers, agents, and theme stay separate. The system tier provides shared defaults so you don’t rebuild common setup per workspace.

The one subtlety: two tiers, two combination modes

Both tiers use the same terms (system and workspace), but they combine in two different ways depending on what you’re configuring.

MERGE — appearance & shortcuts System defaults mode · font · palette Workspace overrides only the fields you set Effective settings field by field, workspace wins COPY — providers, models & agents System catalog built-in · read-only Copy make your own Workspace copy yours to edit · independent

Merge — appearance and shortcuts

For appearance (mode, font size, palette) and keyboard shortcuts, tiers merge into one effective result:

  • System tier: complete defaults
  • Workspace: overrides only fields it sets; unset fields inherit system values
  • Which wins: workspace value for single settings; shortcuts add, re-bind, or unbind

Result: one complete configuration per workspace, no gaps. See Appearance & Theming for controls.

Copy — providers, models, and agents

For providers, models, and agents, tiers do not merge. Each is an independent list:

  • System tier: read-only catalog of built-ins
  • To use: copy into a workspace (connect provider, add model, clone agent) for a copy-then-own pattern. Copies are independent; changes to originals don’t propagate.

No “which tier wins” — system catalog and workspace copies coexist as separate lists.

What you can hand-edit on disk

Configuration is plain files, but prefer the UI where available.

  • Palettes: drop token-only CSS files into a workspace’s themes/ folder — they appear in the picker. This is intentional.
  • Elsewhere: use the UI. Provider/model/agent configs are files, but the app ensures validation and secure key storage (API keys stay in your OS credential store, not configs — see Providers).
  • File locations and field reference: Config files.

What’s shipped today

The two-tier model is in place. A few edges are still being wired:

Settings is the doorway. Details live in the configured concepts: