Settings

Active contributors: Anthony-Eid, danilo-leal, probably-neb

Purpose

Zed's settings stack is JSON-shaped (compatible-feeling with VS Code's settings.json) but typed in Rust under the hood. The system stacks defaults + user + project + local + remote overrides, generates JSON Schemas for IDE auto-complete, and notifies subsystems when relevant keys change.

Crates

Crate	Role
crates/settings	The Settings trait, SettingsStore, registration plumbing
crates/settings_content	Default settings values + bundled assets
crates/settings_json	JSON parsing helpers; comment/trailing-comma tolerance
crates/settings_macros	Procedural macros for deriving Settings
crates/settings_ui	The graphical settings page
crates/settings_profile_selector	UI for switching between settings profiles
crates/schema_generator	Generates JSON Schema for settings (for in-editor autocomplete)

Key abstractions

Type	File	Description
SettingsStore	crates/settings/src/settings_store.rs	Global registry; layered overrides; observers
Settings	crates/settings/src/settings.rs	Trait implemented by every settings struct
BaseKeymap	crates/settings/src/keymap_file.rs (and friends)	Keymap preset (Atom / VS Code / Sublime / JetBrains / …)
KeymapFile	crates/settings/src/keymap_file.rs	Parsed user keymap
SettingsLocation	crates/settings/src/settings_store.rs	Where a setting came from (default / user / project / …)
watch_config_file	crates/settings/src/settings_store.rs	File-watcher that reloads JSON on change

How it works

graph TD
    Defaults[default.json] --> Store[SettingsStore]
    UserCfg[~/.config/zed/settings.json] --> Store
    Project[project/.zed/settings.json] --> Store
    Local[CLI/env overrides] --> Store
    Store -->|typed lookup| Crate1[editor::EditorSettings]
    Store -->|typed lookup| Crate2[agent::AgentSettings]
    Store -->|typed lookup| Crate3[git::GitSettings]
    Store -->|cx.observe| Views[Views re-render on change]

Layering

Lower priority → higher priority:

1. Built-in defaults (crates/settings_content).
2. User settings file.
3. Project-local settings (.zed/settings.json checked in).
4. Workspace-local overrides.
5. Profile selector overrides (crates/settings_profile_selector).
6. Remote settings (crates/recent_projects::RemoteSettings) for SSH targets.

The store performs deep merges so a setting unset at a higher layer falls through to the next one.

Typed access

Each settings owner defines its own struct:

#[derive(Settings)]
#[serde(default)]
pub struct EditorSettings {
    pub cursor_blink: bool,
    pub line_numbers: LineNumbers,
    // ...
}

The Settings derive registers a JSON path and provides a get(cx) accessor that:

• Returns the merged value for the current scope.
• Subscribes the calling view to notify on change.

Schema generation

crates/schema_generator walks every registered Settings impl and emits a JSON Schema. Zed serves this schema to its own JSON LSP, so the user gets autocomplete in settings.json "for free."

Settings UI

crates/settings_ui provides a GUI surface for the most common settings, sitting on top of the same store. It uses crates/settings_content for label/description metadata.

Integration points

• Reads: the JSON files described above + bundled assets in assets/settings/.
• Writes: the user's settings file when the GUI changes a value.
• Notifies: any view holding MySettings::get(cx) re-renders on change.
• Migrations: crates/migrator runs settings migrations on app start (renamed keys, defaults flipped, deprecated values).

Entry points for modification

• Adding a new setting — derive Settings on a new struct, register it during initialisation, add defaults to crates/settings_content.
• Adding a UI surface for an existing setting — crates/settings_ui/src/.
• Migrations — crates/migrator/src/.
• Schema tweaks — crates/schema_generator/src/.

Related pages

• Patterns and conventions — how to consume settings in views
• Editor — heavy consumer of settings
• AI agent — agent settings example