CONFIGURATION.md

Configuration

Runx reads ~/Library/Application Support/runx/config.toml. The file is created on first launch, validated on load, and reloaded when you open Runx after the file changes.

debug_log = true enables diagnostic file logging after restart. Launcher startup rotates debug.log to debug.log.old, and a default launch may create an empty debug.log for fatal-error persistence even when diagnostic logging is disabled. RUNX_LOG enables file logging and accepts tracing EnvFilter directives such as RUNX_LOG=runx=debug,wry=warn; invalid values fall back to runx=info. RUST_LOG is not used. Settings app startup does not rotate or write the launcher log, and settings failures are only visible when stderr is visible.

Top-level options

Root configuration object deserialized from config.toml.

Option	Type	Default	Description
debug_log	boolean	false	Enable diagnostic file logging to debug.log. Changes require restarting Runx. Fatal launcher errors and panics may still create debug.log even when this is false.

[hotkey]

User-facing global hotkey configuration.

Option	Type	Default	Description
shortcut	shortcut string such as Option+Space or Cmd+KeyK	"Option+Space"	Global shortcut that opens the launcher, or empty to disable.
quick_switch	string	"Option+Tab"	Global shortcut that activates quick-switch mode, or empty to disable.

[window]

Launcher window behavior and geometry.

Option	Type	Default	Description
width_fraction	number	0.4	Fraction of the chosen display's logical width used before optional width clamps.
visible_rows	integer	5	Target number of result rows kept visible before optional height clamps.
min_width	number	-	Minimum launcher width in logical pixels.
max_width	number	-	Maximum launcher width in logical pixels.
min_height	number	-	Minimum launcher height in logical pixels.
max_height	number	-	Maximum launcher height in logical pixels.
hide_when_inactive	boolean	true	Hide the launcher automatically when it becomes inactive.
always_on_top	boolean	true	Keep the launcher above normal windows while it is visible.
show_on	one of: primary, cursor	"cursor"	Choose which display Runx appears on when it opens.
scale	number	1	Multiplier applied to UI typography and spacing tokens.
show_animation	boolean	true	Play the macOS zoom animation when showing or hiding the launcher window.

[[display_overrides]]

Per-display overrides for window sizing and scale.

Option	Type	Default	Description
built_in	boolean	-	Match built-in or external displays.
vendor	integer	-	Match the monitor vendor id reported by macOS.
model	integer	-	Match the monitor model id reported by macOS.
serial	integer	-	Match the monitor serial number reported by macOS.
width_fraction	number	-	Override window.width_fraction for matching displays.
visible_rows	integer	-	Override window.visible_rows for matching displays.
min_width	number	-	Override window.min_width for matching displays.
max_width	number	-	Override window.max_width for matching displays.
min_height	number	-	Override window.min_height for matching displays.
max_height	number	-	Override window.max_height for matching displays.
scale	number	-	Override window.scale for matching displays.

[providers]

Provider-specific runtime behavior.

Option	Type	Default	Description
disabled	array of provider names (windows, apps, settings, plugins)	[]	Providers that should not run.

[providers.windows]

Settings for the macOS windows provider.

Option	Type	Default	Description
include_other_desktops	boolean	false	Include windows from other macOS desktops/spaces in search results. Requires Screen Recording permission.
show_on_empty_query	boolean	true	Show open windows before the query is non-empty.

[providers.apps]

Settings for installed application search ranking.

Option	Type	Default	Description
exact_name_boost	integer	200	Score added when a query exactly matches an installed app name.
prefix_name_boost	integer	100	Score added when a query is a prefix of an installed app name.
additional_directories	array of string	[]	Extra directories to scan for .app bundles in addition to the standard app roots.

[ranking]

Ranking and truncation rules for the merged result list.

Option	Type	Default	Description
tie_threshold	integer	120	Maximum raw-score gap that still counts as a tie between providers.
provider_order	array of provider names (windows, apps, settings, plugins)	["windows", "apps", "settings"]	Tie-break priority when multiple providers return similarly scored items.
result_limit	integer	24	Maximum number of rows shown in the launcher.

[ranking.provider_score_boosts]

Per-provider additive score boosts. Use provider names as keys. Omitted providers behave as if their boost were 0.

Option	Type	Default	Description
Provider key	integer	0 when omitted	windows, apps, settings, plugins

[[ranking.score_rules]]

One additive ranking rule matched against a result row.

Option	Type	Default	Description
providers	array of provider names (windows, apps, settings, plugins)	-	Restrict the rule to specific providers. Empty means all providers.
field	one of: title, subtitle, badge, id	-	Result field matched against pattern.
match	one of: exact, prefix, contains	-	Text-matching mode used for pattern.
pattern	string	-	Needle matched against the selected field.
boost	integer	-	Additive score applied when the rule matches.

[timing]

Debounce timings for the search pipeline.

Option	Type	Default	Description
search_debounce_ms	integer	24	Delay before a changed query starts a new search generation.
quick_switch_show_delay_ms	integer	90	Delay before the quick-switch window appears after activation.

[plugins]

Plugin discovery and subprocess lookup configuration.

Option	Type	Default	Description
directories	array of string	[]	Extra directories that should be scanned for .lua plugins.
search_paths	array of string	[]	Extra PATH entries exposed to plugin subprocess helpers.

[[plugins.install]]

A single managed plugin to clone and keep up to date.

Option	Type	Default	Description
source	string	-	Git clone URL or local path.
name	string	-	Override the directory name (defaults to last path segment of source).
ref	string	-	Pin to a specific Git tag. Mutually exclusive with branch.
branch	string	-	Track a branch. Mutually exclusive with ref.

[plugin.<id>]

Per-plugin configuration lives under [plugin.<id>]. Runx passes the full table to the plugin runtime as runx.plugin_config, except for the reserved commands and aliases subtables.

Option	Type	Default	Description
commands	table	-	Reserved for command routing. See [plugin.<id>.commands].
aliases	table	-	Reserved for command aliases. See [plugin.<id>.aliases].
<your keys>	TOML values	-	Arbitrary plugin-specific settings. These are available inside the plugin through runx.plugin_config.

[plugin.<id>.commands]

Command routing maps a typed prefix to a named Lua search handler. A route matches when the query is exactly the command or starts with the command followed by a space. Once a plugin has any configured commands, Runx stops calling its generic search(query) function for unrelated queries. Routed plugins are routed-only.

Option	Type	Default	Description
<command>	string key	-	Command prefix typed into Runx, for example pass or emoji.
value	string	-	Name of the exported Lua handler to call, for example search_type_password.

[plugin.<id>.aliases]

Command aliases provide shorter triggers for existing commands. Each entry maps a canonical command name to an alias string. Typing the alias behaves identically to typing the full command — it is transparent to the plugin.

Option	Type	Default	Description
<command>	string key	-	Canonical command name that has a route.
value	string	-	Alias trigger.

When this section is present, it completely replaces the plugin's built-in aliases. An empty [plugin.<id>.aliases] section disables all default aliases for that plugin. Alias conflicts (duplicate route triggers across all plugins) are rejected at config load time.

[ui]

Theme tokens injected into the embedded HTML/CSS UI templates.

Option	Type	Default	Description
show_header	boolean	true	Show the small header label at the top of the launcher.
cycle_selection	boolean	false	Wrap selection movement from end to start with arrows and Ctrl-N/Ctrl-P.
colorscheme	string (system, builtin_light, builtin_dark, or a custom name matching a file in colorschemes/)	"system"	Selected UI colorscheme: system, a built-in name, or a custom scheme name.
font_family	string	"\"SF Pro Display\", \"Avenir Next\", \"Helvetica Neue\", sans-serif"	CSS font-family stack used by the launcher UI.

[ui.canvas]

Canvas tokens injected into the embedded UI theme.

Option	Type	Default	Description
show	boolean	true	Show the outer launcher panel behind the input and results.
radius	integer	24	Corner radius of the outer launcher panel.
background_opacity	number	0.97	Opacity of the panel fill behind the launcher contents.
chrome_opacity	number	1	Opacity of the panel border and shadow.

[ui.entries]

Entry background tokens injected into the embedded UI theme.

Option	Type	Default	Description
opacity	number	1	Opacity multiplier applied to result-row background surfaces.
show_hover	boolean	true	Show a hover highlight when the mouse is over a result row.
transition_ms	integer	0	Duration of selection/hover transitions in milliseconds (0 = instant).

[ui.shortcuts]

Keyboard shortcuts handled inside the launcher UI.

Option	Type	Default	Description
focus_window	shortcut string such as Enter or Option+Enter, or none	"Enter"	Shortcut for activating the selected window.
activate_all_windows	shortcut string such as Enter or Option+Enter, or none	"Option+Enter"	Shortcut for activating the selected app and bringing all its windows forward.

[ui.font_sizes]

Font-size tokens injected into the embedded UI theme.

Option	Type	Default	Description
label	integer	10	Size of small labels and helper text.
input	integer	30	Search input text size.
title	integer	16	Primary result title text size.
subtitle	integer	12	Secondary result subtitle text size.
badge	integer	11	Badge text size.
accelerator	integer	12	Accelerator chip text size.
config_error_title	integer	24	Config-error title text size.
config_error_body	integer	15	Config-error body text size.

[ui.layout]

Layout tokens injected into the embedded UI theme.

Option	Type	Default	Description
section_gap	integer	14	Gap between top-level shell sections such as input and results.
input_padding_y	integer	14	Vertical padding inside the search input.
input_padding_x	integer	18	Horizontal padding inside the search input.
input_radius	integer	18	Corner radius of the search input.
list_gap	integer	8	Vertical gap between visible result rows.
entry_padding_y	integer	13	Vertical padding inside each result row.
entry_padding_x	integer	14	Horizontal padding inside each result row.
entry_gap	integer	14	Gap between columns inside each result row.
row_radius	integer	18	Corner radius of result rows.
badge_size	integer	46	Size of badge containers.
badge_radius	integer	14	Corner radius of badge containers.
icon_size	integer	46	Size of icon images inside icon badges.

colorschemes/<name>.toml

Custom colorschemes live as individual .toml files in the colorschemes/ directory next to config.toml. The file name (minus .toml) becomes the scheme name. Runx always knows about builtin_light, builtin_dark, and those built-in schemes are read-only. Custom schemes can use any other name and are selected through [ui].colorscheme. Set base to inherit from a built-in palette and make the other tokens optional; without base, every color token must be set. Most users only need accent, canvas_bg, panel, text, and muted; the remaining keys are lower-level UI tokens for precise theme work.

Option	Type	Description
base	one of: builtin_light, builtin_dark	Base palette inherited by a custom scheme. Without base, custom schemes must define every color token.
accent	string	Primary highlight color. In custom schemes, this also derives hover, selected-row, badge, and chip highlight surfaces unless those advanced tokens are set.
panel	string	Panel surface color used by the built-in palette.
text	string	Primary foreground text color.
muted	string	Secondary or de-emphasized foreground text color.
canvas_bg	string	Background fill for the outer launcher canvas.
canvas_shadow	string	Shadow for the outer launcher canvas.
canvas_border	string	Border color for the outer launcher canvas.
label_strong	string	Stronger label color used for prominent small text.
input_bg	string	Background of the search input field.
input_border	string	Border color of the search input field.
input_shadow	string	Shadow of the search input field.
placeholder	string	Placeholder text color in the search input.
scrollbar	string	Scrollbar thumb color inside the results list.
item_bg	string	Default result-row background.
item_hover	string	Result-row background on hover.
item_selected_bg	string	Background of the currently selected result row.
item_selected_shadow	string	Shadow of the currently selected result row.
badge_bg	string	Background of text badges.
badge_border	string	Border color of text badges.
badge_text	string	Foreground text color of text badges.
badge_icon_bg	string	Background behind icon badges.
chip_text	string	Foreground color of accelerator chips.
chip_bg	string	Background color of accelerator chips.
chip_border	string	Border color of accelerator chips.
config_error_bg	string	Background of the dedicated config-error panel.
config_error_border	string	Border color of the config-error panel.
config_error_shadow	string	Shadow of the config-error panel.
config_error_title	string	Title color used in the config-error view.
config_error_copy	string	Body text color used in the config-error view.
canvas_hidden_input_bg	string	Input background when the outer canvas is disabled.
canvas_hidden_input_border	string	Input border when the outer canvas is disabled.
canvas_hidden_input_shadow	string	Input shadow when the outer canvas is disabled.
canvas_hidden_item_bg	string	Result-row background when the outer canvas is disabled.
canvas_hidden_item_hover	string	Result-row hover background when the outer canvas is disabled.
canvas_hidden_item_selected_bg	string	Selected result-row background when the outer canvas is disabled.
canvas_hidden_config_error_bg	string	Config-error panel background when the outer canvas is disabled.