Configuration

AgentNotify is configured through a single per-user JSON file. The file is created on first launch with safe defaults and a generated bearer token. Unknown or malformed fields fall back to defaults; partial files are tolerated and rewritten with missing keys on startup.

Source: src/AgentNotify.Core/Config/AgentNotifyConfig.cs, src/AgentNotify.Core/Config/ConfigStore.cs, src/AgentNotify.Core/Config/NotificationTypeDefinition.cs.

File location and format

Default directory and files (src/AgentNotify.Core/Config/ConfigStore.cs):

%LOCALAPPDATA% is Environment.SpecialFolder.LocalApplicationData. All four paths are derived from the same config directory.

Format: JSON serialized with AgentNotify.Protocol.Json.Options (System.Text.Json with JsonSerializerDefaults.Web, PropertyNameCaseInsensitive: true, JsonStringEnumConverter(JsonNamingPolicy.SnakeCaseLower)). JSON property names are therefore camelCase (port, authToken, toastLocation) while enum strings on the wire are snake_case.

Loading behavior:

• Missing file returns defaults.
• Malformed JSON is caught as JsonException; defaults are kept and a subsequent Save rewrites a healthy file.
• After load AgentNotifyConfig.ApplyDefaults() normalizes and fills missing keys.
• Environment overrides AGENTNOTIFY_PORT and AGENTNOTIFY_TOKEN are applied when ConfigStore(applyEnvOverrides: true) (the CLI default). HasTokenFile and some app startup paths use applyEnvOverrides: false.

Saving is atomic: write to a temporary file then File.Move(overwrite: true).

Warning: config.json contains the local bearer token (authToken). This value authenticates any local process that can reach 127.0.0.1:47821. Do not copy, commit, email, or otherwise share the file. Delete %LOCALAPPDATA%\AgentNotify only when intentionally removing the token, history, and logs.

Settings reference

All settings are properties of AgentNotifyConfig. The table lists the JSON name (as written), the .NET type, the default, and the effect. Validation and clamping described here are performed by ApplyDefaults.

Toast duration defaults

AgentNotifyConfig.DefaultDurations():

During ApplyDefaults:

• An empty or missing map is replaced with the defaults.
• Existing keys are normalized; if the normalized form differs and is absent, the value is copied.
• Every default key is added when absent (TryAdd).

Effective duration is resolved by ToastDurationSeconds(type):

1. If a custom definition is enabled and Id equals the normalized type, its durationSeconds.
2. Else if toastDurations contains the normalized type, that value.
3. Else 7.

Sound policy

NotificationSoundPolicy.ShouldPlay (src/AgentNotify.Core/Services/NotificationSoundPolicy.cs):

if (!soundsEnabled || pauseNotifications) return false;
return !doNotDisturb || (priority == critical && playCriticalSoundsDuringDoNotDisturb);

File resolution uses ManagedSoundStore.Resolve against %LOCALAPPDATA%\AgentNotify\sounds\. Missing files are logged and no sound plays; the notification itself is unaffected.

Files imported through Settings → Sounds are validated by ManagedSoundStore.Import (src/AgentNotify.Core/Services/ManagedSoundStore.cs): must be .wav/.mp3, 1 byte–10 MB, copied with a content-addressed safe name {safeBase}-{hash16}{ext} where safeBase is sanitized to [A-Za-z0-9_-] (max 40). Built-in tones (chime.wav, ping.wav, alert.wav, knock.wav) are seeded idempotently from embedded resources.

Custom notification types

Custom types are presentation and behavior policy stored in customNotificationTypes. Notification rows persist only the stable identifier; deleting or disabling a definition never makes historical rows unreadable — they fall back to generic info styling and a 7-second lifetime.

Schema (src/AgentNotify.Core/Config/NotificationTypeDefinition.cs):

Fallback behavior: a notification whose type has no enabled custom definition uses the built-in toastDurations entry or 7 seconds, normal priority, and generic accent.

Example fragment:

{
 "port": 47821,
 "toastLocation": "BottomRight",
 "customNotificationTypes": [
 {
 "id": "deployment_waiting",
 "displayName": "Deployment waiting",
 "accentColor": "#7C3AED",
 "defaultPriority": "high",
 "durationSeconds": 0,
 "enabled": true
 }
 ]
}

Settings window coverage

The tray Settings window (src/AgentNotify.App/SettingsWindow.xaml, .xaml.cs) edits these config properties directly:

• General tab: port (1–65535), historyRetentionDays (0–3650), pauseNotifications, doNotDisturb.
• Toasts tab: toastLocation, maxVisibleToasts (1–20), eight toastDurations entries (0–86400 each).
• Custom types tab: full customNotificationTypes CRUD with the validation rules above.
• Sounds tab: soundsEnabled, soundVolume (0–100), playCriticalSoundsDuringDoNotDisturb, defaultSoundFile, typeSoundFiles, built-in tone picker (Chime, Ping, Alert, Knock) and WAV/MP3 import.
• Channels tab: provider profiles and delivery routes (persisted in SQLite, not in config.json).

These properties have no control in the Settings window and are edited by editing config.json or through the tray menu / environment:

• authToken — generated and shown only via agentnotify token or the file itself.
• apiVersion — read-only.
• maxRequestBodyBytes, rateLimitPerSecond, maxMetadataBytes — code defaults and file edits only.
• launchAtStartup — toggled from the tray menu (registry is the source of truth; reconciled to the file on startup).