Skip to content

Configuration field reference ​

ZoneDeck stores its configuration in config.json — in the program folder for a portable copy, in %APPDATA%\ZoneDeck for an installed one; see Data folder. When the location changes, the old configuration is migrated across automatically. The structure is fully compatible with older versions, so existing configurations carry over. If the file is missing on first run, defaults are used. The field definitions live in crates/common/src/config.rs.

You normally do not edit this by hand

The settings window reads and writes the configuration automatically. This page is for developers who need to understand the fields.

Top level ​

FieldTypeDescription
versionstringConfiguration schema version; only changes when the structure does
app_versionstringThe program version last seen; when it differs from the current one this is the first run after an update, and the core opens the settings window automatically. Empty by default
historynumber[]History (timestamps)
frozen_pidsnumber[]PIDs of currently frozen processes (used for recovery)
hotkeyobjectKeyboard hotkeys; see below
settingobjectMain settings; see below
notificationsobjectNotification switches; see below
verhubobjectUpdates / announcements; see below
window_rulesobject[]Window rules (fine-grained)
process_rulesobject[]Process rules (coarse-grained)
whitelistobject[]Whitelist: per-process opt-out of hiding / freezing / muting
hide_bindingobject[]v2 flat bindings, used only for migration; cleared afterwards and never written back

hotkey ​

FieldDefaultDescription
hide_hotkey"Ctrl+Q"Hide / show windows
close_hotkey"Win+Esc"Close the core
hide_only_hotkey""Hide windows only; empty means disabled
show_only_hotkey""Show windows only; empty means disabled
hide_foreground_hotkey""Hide foreground window; empty means disabled
hide_hookfalseTrigger the hide hotkey through the low-level keyboard hook
close_hookfalseTrigger the close hotkey through the low-level keyboard hook
hide_only_hookfalseTrigger the hide-only hotkey through the low-level keyboard hook
show_only_hookfalseTrigger the show-only hotkey through the low-level keyboard hook
hide_foreground_hookfalseTrigger the hide-foreground hotkey through the low-level keyboard hook
hide_interceptfalseDon't pass the hide hotkey through; when true, hide_hook is forced true as well
close_interceptfalseDon't pass the close hotkey through
hide_only_interceptfalseDon't pass the hide-only hotkey through
show_only_interceptfalseDon't pass the show-only hotkey through
hide_foreground_interceptfalseDon't pass the hide-foreground hotkey through

Hotkey strings support richer combinations: several main keys joined with + (up to four, e.g. "Q+W"), or modifiers alone for a modifier-only hotkey (e.g. "Ctrl+Shift"). Only the keyboard hook can carry those two kinds, so the core routes them through it even when the matching *_hook is off. Punctuation keys are stored by key position (OEM_1, OEM_PLUS and so on) and do not shift with the keyboard layout.

setting ​

FieldTypeDefaultFeature
mute_after_hidebooltrueMute after hiding
send_before_hideboolfalsePause playback as well: tries to pause playing media as the windows are hidden
resume_media_after_showboolfalseResume playback on restore: depends on send_before_hide; the choice is fixed at hide time
minimize_before_hideboolfalseMinimise windows before hiding
hide_currentbooltrueAlso hide the active window
hide_icon_after_hideboolfalseAlso hide ZoneDeck's tray icon
hide_config_after_hidebooltrueAlso hide the ZoneDeck settings window: only applies to a settings window visible at that moment
tray_enabledbooltrueShow the tray icon; when false the icon never appears and balloons / badges go with it
tray_clicksobjectSee belowTray icon click actions
tray_badgesobjectSee belowTray icon status
tray_show_tooltipbooltrueTray icon tooltip
freeze_after_hideboolfalseFreezing master switch
enhanced_freezeboolfalseEnhanced freezing
power_scopestring"self"Freezing & memory scope: self (target process only) | tree (and all its children) | image (all instances of the same image name); governs freezing and memory trimming, unknown values normalise to self
efficiency_after_hideboolfalseEfficiency mode: drop hidden processes to EcoQoS + low priority; independent of freezing
efficiency_scopestring"self"Efficiency mode scope, same values as power_scope, independent of the freezing scope
trim_memory_after_freezeboolfalseReduce memory usage (frozen processes only)
show_float_windowboolfalseFloating window (in development)
mouseobjectSee belowHiding with mouse buttons
auto_hide_enabledboolfalseAuto-hide when idle
auto_hide_timenumber5Idle time (minutes, 1–120)
top_left_hide and the other cornersboolfalseCorner hiding
corner_fast_onlybooltrueOnly trigger on fast movement
allow_move_restoreboolfalseRestore from a corner
log_retention_daysnumber7Log retention (0 = off)
log_levelstring"warn"Log level: debug | info | warn | error
autostart_adminboolfalseStart as administrator (scheduled-task method only)
languagestring"auto"Display language: auto | zh-CN | en | zh-TW
Legacy flat mouse switches (deprecated)

middle_button_hide / side_button1_hide / side_button2_hide exist only for deserialisation and migration; they are cleared afterwards and never written back. Use the mouse structure instead.

Legacy "freeze the whole process tree" switch (deprecated)

freeze_whole_tree exists only for deserialisation and migration: if a config has no power_scope, true migrates to power_scope: "tree" and false to "self", after which the old key is cleared and never written back. Configs that already set power_scope explicitly are unaffected.

Legacy "toggle hiding by clicking the tray icon" switch (deprecated)

click_to_hide exists only for deserialisation and migration: if a config has no tray_clicks, true migrates to tray_clicks.left: "toggle" and false to "none", after which the old key is cleared and never written back. Configs that lack the key entirely are treated as true (the old default was on). Configs that already set tray_clicks explicitly are unaffected.

setting.tray_clicks ​

Tray icon click actions: each of the three clicks gets one action, out of none (do nothing) | toggle (hide / show windows) | menu (open the tray menu) | settings (open the settings window). Unknown values normalise to none.

FieldDefaultDescription
left"toggle"Single click
double"settings"Double click. When it is not none, a single click waits out the system double-click time before running
right"menu"Right click

setting.mouse ​

Each button is a MouseButton: { enabled: bool, clicks: 1..=3, modifiers: string }.

FieldDefaultDescription
left / middle / right / side1 / side2See belowThe trigger condition for each of the five buttons
multi_click_ms350Multi-click interval (milliseconds, 150–1000)
allow_click_restoretrueAllow restoring by pressing again

Defaults for a fresh installation

A fresh installation enables a middle-button double click (middle.enabled = true, clicks = 2) and leaves the other four off. An old configuration without a mouse section reads as all off.

setting.tray_badges ​

Tray icon status: each of the four colored dot badges is bound to a state source; when several bound states are active at once, only one dot is shown, in red > green > yellow > blue priority order.

FieldDefaultDefault meaning
red"hidden"Windows are hidden
green"auto_hide"Auto hide is enabled
yellow"hide_current"Also-hide-active-window is enabled
blue"freeze"Process freezing is enabled

Each field accepts hidden (windows are hidden) | auto_hide (auto hide is enabled) | hide_current (also-hide-active-window is enabled) | freeze (process freezing is enabled) | elevated (running as administrator) | monitor_paused (hotkey monitoring is paused) | "" (empty = do not show that color); unknown values are normalised to empty on read.

notifications ​

FieldDefaultDescription
on_starttrueCore started
on_quittrueCore exited
on_autostarttrueStartup setting changed
on_hidefalseEvery hide
on_showfalseEvery show
on_recovery_mismatchtrueNotify when, after an abnormal exit, some hidden-window records no longer match what was recorded

verhub ​

FieldDefaultDescription
include_previewfalseWhether update checks include preview releases
seen_announcement_id""The id of the newest announcement already read
analyticsnullConsent for anonymous usage statistics: null means the user has not been asked yet and the first run prompts for it; true granted, false declined
analytics_consent_sentfalseWhether the "took part" event has already been sent. One per device; toggling the switch again does not resend it

window_rules ​

Fine-grained rules targeting a single window by handle plus title. When regex is Some, matching is by title regex.

FieldDescription
titleWindow title
hwndWindow handle
processProcess name
PIDProcess ID (uppercase key, for compatibility with old configurations)
pathExecutable path
regexTitle regex (advanced mode; omitted means an exact rule)
include_untitledWhether the regex includes untitled windows
include_backgroundWhether the regex includes background windows

process_rules ​

Coarse-grained rules that hide every window of a program, matched by executable.

FieldDefaultDescription
processProcess name
pathExecutable path
regexRegex (applied to the path or the file name)
by_namefalseMatch on the file name only, ignoring the path
include_untitledtrueWhether to include untitled windows (process rules include them by default)
include_backgroundfalseWhether to include background windows

whitelist ​

Declares, per process, which modes to skip; see Whitelist. Matching mirrors process_rules, except it defaults to file-name matching, and both file names and paths compare case-insensitively.

FieldDefaultDescription
processProcess name
pathExecutable path
regexRegex (applied to the path or the file name)
by_nametrueMatch on the file name only, ignoring the path
ignore_hidefalseNever hide this program's windows
ignore_freezefalseNever freeze this program's processes after hiding
ignore_mutefalseNever mute this program's processes after hiding

Missing key vs empty array

When the whitelist key is absent (old or brand-new configs), a default explorer.exe entry is seeded. Writing [] means the user emptied the list and nothing is seeded again. After normalization the field is always an array, never null.

ZoneDeck's own core and settings app (ZoneDeck.exe / core.exe / config.exe / zonedeck-config.exe) are always excluded from freezing. That guard lives in BUILTIN_FREEZE_GUARDS in crates/common/src/matching.rs, never appears in the config file, and cannot be bypassed by editing it.

Compatibility and migration ​

  • Unknown fields are ignored: fields added later do not break parsing in an older core.
  • Missing fields use defaults: any missing field falls back to its default.
  • Corrupt files are backed up first: if the whole file fails to parse, it is renamed to config.json.bad in the same directory before defaults take over, so rules can be recovered manually; the backup location is recorded in the log.
  • Old bindings migrate automatically: hide_binding → window_rules; the old mouse switches → mouse click triggers. Migration is idempotent.
  • Uppercase PID: serialisation emits an uppercase PID, compatible with the old Python versions.