Central registry for typed editor options.
Stores global option values and per-filetype overrides. Other modules
read options via get/1 (global) or get_for_filetype/2 (merged with
filetype overrides).
Backed by ETS with read_concurrency: true for lock-free reads on
every render frame and keystroke. The GenServer exists only to own
the ETS table lifecycle. Reads go directly to ETS; writes validate
and then insert directly (no GenServer round-trip needed since ETS
writes are atomic per-key).
Supported options
Option metadata lives in @option_specs, including each option's type, default value, and user-facing description. Use option_specs/0 for the full list, describe/1 for one built-in option, and extension_option_specs/1 for extension-registered options.
Log level options control per-subsystem verbosity. Subsystem options default to :default (inherit from :log_level). See Minga.Log for the filtering API.
Per-filetype overrides
Per-filetype settings override globals for buffers of that type:
Minga.Config.Options.set_for_filetype(:go, :tab_width, 8)
Minga.Config.Options.get_for_filetype(:tab_width, :go)
#=> 8Example
Minga.Config.Options.set(:tab_width, 4)
Minga.Config.Options.get(:tab_width)
#=> 4Summary
Types
Human-readable metadata for an extension option.
Line number display style.
Human-readable metadata for one option.
Valid option names.
Option spec: {name, type_descriptor, default_value, description}.
Reference to a Config.Options GenServer (registered name or pid).
Options server state.
ETS table reference used for reads and writes.
Functions
Returns all current global option values as a map.
Returns a specification to start this module under a supervisor.
Returns the default value for an option.
Returns the registered name of the default options server.
Returns metadata for an option, or nil if unknown.
Returns metadata for a registered extension option, or nil if unknown.
Returns whether an option was explicitly set by the GUI settings overlay.
Returns the description string for an extension option, or nil if
not found.
Returns metadata for all registered extension options.
Returns the config-level provenance chain for an extension option's effective value.
Returns the registered option schema for an extension, or nil if
the extension has no schema.
Gets the current global value of an option, falling back to its default.
Gets an extension option value, falling back to its registered default.
Gets an extension option with filetype override applied.
Gets an option value with filetype override applied.
Marks an option as explicitly set by the GUI settings overlay.
Returns the full option spec list: [{name, type, default, description}].
Returns the config-level provenance chain for an option's effective value.
Registers a typed option for use by an extension.
Resets all options (global and per-filetype) to defaults.
Sets a global option value after type validation.
Sets an extension option value after type validation.
Sets an extension option override for a specific filetype.
Sets an option override for a specific filetype.
Starts the options registry and creates the backing ETS table.
Returns the type descriptor for an option, or nil if unknown.
Returns the list of valid option names.
Validates an option name and value against the type registry.
Asserts that server is a valid server/0 reference (pid or non-nil atom).
Types
@type extension_option_metadata() :: %{ extension: atom(), name: atom(), type: type_descriptor(), default: term(), description: String.t() }
Human-readable metadata for an extension option.
@type line_number_style() :: :hybrid | :absolute | :relative | :none
Line number display style.
@type option_metadata() :: %{ name: option_name(), type: type_descriptor(), default: term(), description: String.t() }
Human-readable metadata for one option.
@type option_name() ::
:editing_model
| :space_leader
| :tab_width
| :line_numbers
| :show_gutter_separator
| :autopair
| :autopair_block
| :scroll_margin
| :scroll_lines
| :theme
| :indent_with
| :indent_guides
| :show_invisible
| :trim_trailing_whitespace
| :insert_final_newline
| :format_on_save
| :auto_save_delay_ms
| :lsp_auto_start
| :formatter
| :title_format
| :modeline_left_segments
| :modeline_right_segments
| :modeline_separator
| :recent_files_limit
| :persist_recent_files
| :persist_known_projects
| :clipboard
| :wrap
| :linebreak
| :breakindent
| :agent_provider
| :agent_model
| :agent_tool_approval
| :agent_destructive_tools
| :agent_tool_permissions
| :agent_hooks
| :agent_session_retention_days
| :agent_session_idle_timeout_ms
| :agent_panel_split
| :startup_view
| :agent_auto_context
| :agent_max_tokens
| :agent_max_retries
| :agent_models
| :agent_prompt_cache
| :agent_notifications
| :agent_notify_on
| :agent_system_prompt
| :agent_append_system_prompt
| :agent_diff_size_threshold
| :agent_max_turns
| :agent_max_cost
| :agent_api_base_url
| :agent_api_endpoints
| :agent_mcp_servers
| :agent_compaction_threshold
| :agent_compaction_keep_recent
| :agent_approval_timeout
| :agent_subagent_timeout
| :agent_mention_max_file_size
| :agent_notify_debounce
| :agent_diagnostic_feedback
| :agent_flush_before_shell
| :confirm_quit
| :line_spacing
| :font_family
| :font_size
| :font_weight
| :font_ligatures
| :font_fallback
| :prettify_symbols
| :whichkey_layout
| :log_level
| :log_level_render
| :log_level_lsp
| :log_level_agent
| :log_level_editor
| :cursorline
| :cursor_animate
| :cursor_blink
| :nav_flash
| :nav_flash_threshold
| :log_level_config
| :log_level_port
| :log_level_distribution
| :log_level_ext
| :parser_tree_ttl
| :event_retention_days
| :event_persist_all
| :event_size_cap_mb
| :default_shell
| :file_find_excludes
| :picker_backdrop
Valid option names.
@type option_spec() :: {option_name(), type_descriptor(), term(), String.t()}
Option spec: {name, type_descriptor, default_value, description}.
@type server() :: GenServer.server()
Reference to a Config.Options GenServer (registered name or pid).
@type state() :: %{ table: :ets.table(), source: server(), events_registry: Minga.Events.registry() }
Options server state.
@type table() :: :ets.table()
ETS table reference used for reads and writes.
@type type_descriptor() :: :pos_integer | :non_neg_integer | :integer | :boolean | :atom | {:enum, [atom()]} | :theme_atom | :string | :string_or_nil | :string_list | :atom_list | :map_or_nil | :map_list | :float_or_nil | :any
Functions
@spec all(server()) :: %{required(option_name()) => term()}
Returns all current global option values as a map.
Returns a specification to start this module under a supervisor.
See Supervisor.
@spec default(option_name()) :: term()
Returns the default value for an option.
@spec default_server() :: server()
Returns the registered name of the default options server.
@spec describe(atom()) :: option_metadata() | nil
Returns metadata for an option, or nil if unknown.
@spec describe_extension_option(server(), atom(), atom()) :: extension_option_metadata() | nil
Returns metadata for a registered extension option, or nil if unknown.
@spec explicitly_set?(server(), option_name()) :: boolean()
Returns whether an option was explicitly set by the GUI settings overlay.
Returns the description string for an extension option, or nil if
not found.
Used by SPC h v (describe option) and other introspection features.
@spec extension_option_specs(server()) :: [extension_option_metadata()]
Returns metadata for all registered extension options.
Returns the config-level provenance chain for an extension option's effective value.
@spec extension_schema(server(), atom()) :: [Minga.Extension.option_spec()] | nil
Returns the registered option schema for an extension, or nil if
the extension has no schema.
@spec get(server(), option_name()) :: term()
Gets the current global value of an option, falling back to its default.
Gets an extension option value, falling back to its registered default.
Examples
Config.Options.get_extension_option(:minga_org, :conceal)
# => trueGets an extension option with filetype override applied.
Checks filetype-specific override first, then falls back to the global extension option value.
@spec get_for_filetype(server(), option_name(), atom() | nil) :: term()
Gets an option value with filetype override applied.
Checks filetype-specific settings first, then falls back to the global
value. If filetype is nil, returns the global value.
@spec mark_explicit(server(), option_name()) :: :ok
Marks an option as explicitly set by the GUI settings overlay.
@spec option_specs() :: [option_spec()]
Returns the full option spec list: [{name, type, default, description}].
Used by Config.Completion to generate completion items with
type and default information in the detail text.
@spec provenance(option_name(), atom() | nil) :: [String.t()]
Returns the config-level provenance chain for an option's effective value.
@spec provenance(server(), option_name(), atom() | nil) :: [String.t()]
@spec register_extension_schema( server(), atom(), [Minga.Extension.option_spec()], keyword() ) :: :ok | {:error, String.t()}
Registers a typed option for use by an extension.
Registers a full option schema for an extension and validates user
config against it. Called by Extension.Supervisor at load time,
not by extensions directly.
Each spec in the schema is stored under {:extension, ext_name, opt_name}
in ETS, with type metadata under {:extension_schema, ext_name}.
User config values that match a schema entry are validated and stored. Unknown keys produce a warning log. Type mismatches return an error.
@spec reset(server()) :: :ok
Resets all options (global and per-filetype) to defaults.
@spec set(server(), option_name(), term()) :: {:ok, term()} | {:error, String.t()}
Sets a global option value after type validation.
Returns {:ok, value} on success or {:error, reason} if the option
name is unknown or the value has the wrong type.
@spec set_extension_option(server(), atom(), atom(), term()) :: {:ok, term()} | {:error, String.t()}
Sets an extension option value after type validation.
Examples
Config.Options.set_extension_option(:minga_org, :conceal, false)
# => {:ok, false}@spec set_extension_option_for_filetype(server(), atom(), atom(), atom(), term()) :: {:ok, term()} | {:error, String.t()}
Sets an extension option override for a specific filetype.
The value is validated against the extension's registered schema.
Examples
Config.Options.set_extension_option_for_filetype(:minga_org, :org, :conceal, false)@spec set_for_filetype(server(), atom(), option_name(), term()) :: {:ok, term()} | {:error, String.t()}
Sets an option override for a specific filetype.
The value is validated the same way as global options.
@spec start_link(keyword()) :: GenServer.on_start()
Starts the options registry and creates the backing ETS table.
Pass name: nil to start anonymously (no registered name, unnamed ETS
table). Useful for isolated test fixtures: pass the returned pid to
server-aware functions instead of generating per-test atoms.
@spec type_for(option_name()) :: type_descriptor() | nil
Returns the type descriptor for an option, or nil if unknown.
Used by Config.Completion to determine what value completions
to offer (enum variants, booleans, etc.).
@spec valid_names() :: [option_name()]
Returns the list of valid option names.
Validates an option name and value against the type registry.
Returns :ok if valid, or {:error, reason} if the name is unknown
or the value has the wrong type. Used by Buffer.set_option/3
to validate buffer-local option overrides.
Asserts that server is a valid server/0 reference (pid or non-nil atom).
Raises ArgumentError otherwise. Use at boundaries that accept a caller-
supplied :options_server opt — bad values would otherwise silently
short-circuit later (e.g. Process.get(:minga_config_options, default)
returns nil if the key is set to nil, defeating the fallback).