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 data directory (src/AgentNotify.Core/Config/ConfigStore.cs):

Every platform derives the same files from that directory:

agentnotifyd --config-dir <path> selects a different absolute data directory for a headless broker. On Unix, the directory and sensitive files are created with owner-only permissions. See INSTALLATION_UNIX.md and ../SECURITY.md for keyring and fallback-key details.

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 the platform data directory only when intentionally removing the token, configuration, history, provider state, 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 the data directory's sounds/ folder. 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.

Agent home override

AGENTNOTIFY_AGENT_HOME, when set in the environment of agentnotifyd, is the home directory the router's agent connectors look under for .codex/ and .claude/, instead of the broker user's own. It exists so a second agent profile — or a verification run — can be connected without touching the owner's real Codex and Claude Code configuration. It is read at broker start.

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 web interface edits the same properties as the tray Settings window, on every platform, except launchAtStartup, which stays in the Windows tray menu. Live quota also edits macMenuBar, which has no WPF Settings control because it belongs to the macOS host.

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, routerMaxRequestBodyBytes, routerLedgerRetentionDays — code defaults and file edits only.
• launchAtStartup — toggled from the tray menu (registry is the source of truth; reconciled to the file on startup).