Configuration Reference

Configuration Reference

TrayIconGuard has exactly one configuration file — %APPDATA%\TrayIconGuard\settings.json — plus a small, documented registry surface. There are no environment variables, no machine-wide policy, and no INI files. Missing keys fall back to compiled defaults; unknown keys are ignored; writes are atomic (temporary file + replace). Everything below is traced to src/core/settings.h / settings.cpp and verified against a file the program actually wrote during the Wine test run.

---

Contents

• File location and shape
• appearance group
• behavior group
• guard group
• icons group
• updates group
• install group
• state group
• Registry surface
• Data folders
• See also

---

File location and shape

%APPDATA%\TrayIconGuard\settings.json        (roaming profile, per user)

Schema marker "schema": 8; the writer also stamps "app": "TrayIconGuard <kVersion>". Hand-editing is supported: the loader clamps what it understands and ignores the rest (docs/TROUBLESHOOTING.md). A verified sample (defaults, as written on first run):

{
  "schema": 8,
  "app": "TrayIconGuard 8.3.0",
  "appearance": { "theme": 0, "accent": "system", "language": "auto",
                  "animations": true, "compactRows": false },
  "behavior": { "startMinimized": false, "closeToTray": true, "autoStart": false,
                "notifications": true, "confirmExplorerRestart": true, "autoBackup": true },
  "guard": { "enabled": true, "debounceMs": 400, "pollMs": 0,
             "autoRestartExplorer": false, "explorerCooldownSec": 60,
             "legacyBelt": true, "displayMode": "custom" },
  "icons": { "userHidden": [], "order": [], "exclusions": [] },
  "updates": { "checkEnabled": false, "feedUrl": "", "lastCheck": 0 },
  "install": { "mode": "unknown", "dir": "" },
  "state": { "firstRunDone": true, "lastPage": "dashboard",
             "winX": -1, "winY": -1, "winW": 0, "winH": 0, "winMax": false }
}

appearance group

Key	Type	Default	Effect
theme	int	0	0 System · 1 Light · 2 Dark; out-of-range loads as System. System follows Themes\Personalize\AppsUseLightTheme live via WM_SETTINGCHANGE(ImmersiveColorSet)
accent	string	"system"	"system" = Windows colorization color; else #RRGGBB from the eight presets (#0F6CBD #744DA9 #0E7070 #0F7B0F #98450C #C239B3 #9A0021 #4C5B66)
language	string	"auto"	"auto" resolves through the OS UI language; else a BCP-47 primary tag among the 30 locales; unknown → en. Legacy "ru"/"en" still accepted
animations	bool	true	false freezes all widget animations at their target values
compactRows	bool	false	Icons-page row height 40 px instead of 56 px

behavior group

Key	Type	Default	Effect
startMinimized	bool	false	GUI starts hidden in the notification area (autostart passes --minimized regardless)
closeToTray	bool	true	Close button hides the window; Shift+close always exits; first hide shows a hint balloon once
autoStart	bool	false	Keeps the HKCU Run entry installed; GUI reconciles registry against this flag at startup
notifications	bool	true	Balloon toasts when the guard promotes icons
confirmExplorerRestart	bool	true	TaskDialog confirmation before manual Explorer restarts from the UI
autoBackup	bool	true	Snapshot before bulk changes (--promote-all, UI Promote all, restore operations)

guard group

Key	Type	Default	Clamp on load	Effect
enabled	bool	true	—	Master switch; first run forces true
debounceMs	int	400	50–5000	Quiet period after a registry wake before a reconcile pass; UI offers 200/400/800/1500
pollMs	int	0	≥0	Poll timer for the guard loop; 0 means “event-driven only” — see The Guard Watcher for why polling is currently the path that reconciles in published builds; UI offers Off/2/5/15 s
autoRestartExplorer	bool	false	—	Restart the shell after two consecutive fixing passes once the cooldown elapsed
explorerCooldownSec	int	60	≥10	Minimum gap between automatic Explorer restarts; UI offers 30/60/120/300
legacyBelt	bool	true	—	Keep EnableAutoTray=0 written as belt-and-suspenders
displayMode	string	"custom"	full/compact, else custom	Visibility policy for reconcile passes

icons group

Key	Type	Default	Effect
exclusions	string[]	[]	Case-insensitive wildcards matched against executable file name and full path; excluded icons stay hidden in custom mode and are skipped by promote-all
userHidden	string[]	[]	Icon ids the user explicitly hid in custom mode (per-icon intent, distinct from exclusions)
order	string[]	[]	Drag-reorder persistence: listed ids first (top-down), remaining icons alphabetical

updates group

Key	Type	Default	Effect
checkEnabled	bool	false	Opt-in silent auto-check; at most once per 24 h; shows a balloon only — never downloads or applies
feedUrl	string	""	Empty = built-in default feed (…/main/update/stable.json); otherwise any URL the updater's allow-list accepts (https, or loopback http for QA)
lastCheck	int	0	Epoch seconds of the last auto-check (24 h gate)

install group

Key	Type	Default	Effect
mode	string	"unknown"	unknown triggers the first-run wizard; installed or portable afterwards. About page offers Install to this PC… while not installed
dir	string	""	Install folder chosen in the wizard (default %LOCALAPPDATA%\Programs\TrayIconGuard)

state group

Key	Type	Default	Effect
firstRunDone	bool	false	Until the first successful save: welcome balloon + one-shot promote-all on GUI start
lastPage	string	"dashboard"	Page restored on launch; one of the seven page names
winX/winY	int	-1	Restored window position (-1 = system default)
winW/winH	int	0	Restored size; values below 700×500 fall back to 1060×700; window minimum is 720×520
winMax	bool	false	Restore maximized

Registry surface

All writes are HKCU; nothing touches HKLM except two reads for OS edition and display version (src/core/os.cpp).

Key	Value(s) written	When
Control Panel\NotifyIconSettings\{id}	IsPromoted (DWORD 0/1)	reconcile passes, promote/restore commands
Software\Microsoft\Windows\CurrentVersion\Explorer	EnableAutoTray = 0 / deleted	legacy belt on/off, --restore-defaults
Software\Microsoft\Windows\CurrentVersion\Policies\Explorer	deletes HideSCAVolume/HideSCANetwork/HideSCAPower when 1	promote-all and the Guard-page repair
Software\Classes\Local Settings\…\TrayNotify	deletes IconStreams, PastIconsStream	explicit cache-reset repair only
Software\Microsoft\Windows\CurrentVersion\Run	TrayIconGuard = "<exe>" --minimized / deleted	autostart install/remove
Software\Microsoft\Windows\CurrentVersion\Uninstall\TrayIconGuard	DisplayName, DisplayVersion, Publisher, InstallLocation, UninstallString, DisplayIcon, NoModify, NoRepair	wizard/installer::Install; tree deleted by --uninstall

Reads: Themes\Personalize\AppsUseLightTheme, DWM\ColorizationColor, SOFTWARE\Microsoft\Windows NT\CurrentVersion (EditionID, DisplayVersion/ReleaseId).

Data folders

Folder	Contents	Retention
%APPDATA%\TrayIconGuard\	settings.json	until uninstall/delete
%LOCALAPPDATA%\TrayIconGuard\logs\	TrayIconGuard-yyyyMMdd.log	14 days, pruned at log init
%LOCALAPPDATA%\TrayIconGuard\backups\	TrayIconState-<timestamp>.json	newest 30 kept

---

See also

• Command-Line Interface — flags that override or mirror these settings
• The Guard Watcher — semantics of the guard.* knobs
• Backups and Snapshots — snapshot schema and retention
• Security and Privacy — why there is deliberately no machine-wide configuration