# User settings

> Configure global Zuse defaults and understand persisted preferences.

Canonical URL: https://docs.zuse.sh/reference/settings



Zuse stores global preferences in:

```text
~/.zuse/settings.json
```

The settings UI is the safest way to edit this file. Changes are validated and synchronized through the running desktop service.

## Main preference groups [#main-preference-groups]

| Group      | Persisted behavior                                                            |
| ---------- | ----------------------------------------------------------------------------- |
| Defaults   | Provider, model by provider, runtime permission mode, worktree creation       |
| Appearance | System, light, or dark mode                                                   |
| Completion | Sound enabled state and sound preset                                          |
| Providers  | Enabled providers and visible models                                          |
| OpenCode   | Connected provider visibility, model visibility, and custom provider metadata |
| MCP        | Globally disabled provider-native servers                                     |
| Subagents  | Default enablement and preset overrides                                       |
| Git        | Branch naming style/prefix and merge preferences                              |
| Privacy    | Usage analytics preference                                                    |
| Desktop    | Notch tray enablement and pinning                                             |

Repository values such as provider, model, runtime mode, and worktree default can override global choices for one project. Put shared project behavior in `.zuse/settings.toml`, not this user file.

## Direct editing [#direct-editing]

If you edit JSON manually, close Zuse first and keep `schemaVersion` at `1`. Unknown properties are rejected. Use:

```text
https://zuse.dev/schemas/settings.schema.json
```

The file does not contain provider API keys. App-managed secret material belongs in the macOS Keychain.

## Settings surfaces [#settings-surfaces]

The app separates global settings into **General**, **Providers**, **MCP Servers**, **Integrations**, **Devices**, **Browser**, **Pokedex**, **Keyboard shortcuts**, and **Diagnostics**. Projects listed below those global entries open their committed repository settings. Some sections appear only when their platform capability or integration is available.