# How to Configure the Wedge Alarm for Away-Mode Notifications in Firstmate > Configure Firstmate wedge alarm away mode notifications using config files or environment variables. Customize alerts for away mode escalations. - Repository: [Kun Chen/firstmate](https://github.com/kunchenguid/firstmate) - Tags: how-to-guide - Published: 2026-08-13 --- **Configure the git-ignored `config/wedge-alarm` file with notification directives such as `osascript`, `herdr`, or `command:/path/to/script`, or override at runtime using the `FM_WEDGE_ALARM_CHANNEL` environment variable to customize how Firstmate alerts you when away-mode escalations exceed `FM_MAX_DEFER_SECS`.** The **wedge alarm** in kunchenguid/firstmate protects against missed away-mode escalations by notifying the captain when deferrals exceed the safety threshold. Proper configuration ensures you receive time-critical alerts through your preferred channels without disrupting your terminal workflow. ## Configuring the Wedge Alarm Channel ### The config/wedge-alarm File The primary configuration resides in **`config/wedge-alarm`**, a git-ignored file in your Firstmate repository. Each non-empty, non-comment line represents a notification directive that the away-mode sub-supervisor attempts in sequence. The daemon reads this file fresh each time it needs to emit an alarm, so changes take effect on the next trigger without requiring a full restart. According to the implementation in [`bin/fm-supervise-daemon.sh`](https://github.com/kunchenguid/firstmate/blob/main/bin/fm-supervise-daemon.sh) (line 21), if this file does not exist, Firstmate defaults to the `auto` directive. On macOS, this resolves to `osascript`; on other platforms, the alarm relies on any `command:` directives you provide or remains silent except for the durable marker and tmux flash indicators. ### Runtime Override with FM_WEDGE_ALARM_CHANNEL For testing or temporary channel switching, set the **`FM_WEDGE_ALARM_CHANNEL`** environment variable. When present, this variable replaces the entire contents of `config/wedge-alarm` with a single directive. This override is useful for CI pipelines or debugging sessions where you want to redirect alerts to stdout or a test harness. ## Available Notification Directives Firstmate supports five distinct directive types in the wedge alarm configuration. Each channel is **best-effort**: if execution fails (binary missing, non-zero exit), the supervisor logs a warning and proceeds to the next directive (line 25). ### Platform-Specific Channels **`auto`** or **`default`** resolves platform-appropriately. On macOS, this triggers `osascript`; on Linux and other systems, it falls back to the durable marker unless overridden by explicit `command:` directives. **`osascript`** dispatches a macOS Notification Center banner outside the terminal pane. This directive only functions on macOS systems with the `osascript` binary available. **`herdr`** invokes `herdr notification show` to display alerts outside the supervised pane. This requires the Herdr notification manager to be installed and available in the system PATH. ### Custom Command Execution **`command:`** executes the specified command via `sh -c`, passing the alarm summary as `$1` and on stdin. Use this to forward alerts to Slack, PagerDuty, SMS gateways, or custom monitoring services. Failures are logged but do not crash the daemon. ### Disabling Active Alerts **`off`** suppresses all active notification attempts while preserving the durable marker and tmux flash visual indicators. Use this during debugging or when operating in sensitive environments where audible or external alerts are prohibited. ## Safety Mechanisms and Rate Limiting The wedge alarm incorporates several safeguards to prevent notification spam and hanging processes. **Rate limiting** ensures the alarm fires only after a genuine max-defer wedge and is limited to **once per `FM_MAX_DEFER_SECS` window** (line 22). This prevents duplicate alerts during extended away-mode sessions. **Execution timeouts** bound all invocations by **`FM_WEDGE_ALARM_TIMEOUT_SECS`** (default 10 seconds) to avoid blocking the supervisor indefinitely (line 26). **Test seam injection** via **`FM_WEDGE_ALARM_EXEC`** defaults to a discard function in test environments, preventing accidental real notifications during automated test runs (lines 31-34). ## Practical Configuration Examples ### macOS Notification Center Default Create `config/wedge-alarm` with: ```text auto ``` On macOS, this resolves to `osascript` and displays a native Notification Center banner. On other platforms, ensure you add a `command:` directive for audible or external alerting. ### Custom Slack Integration Forward alerts to a Slack webhook using: ```text # config/wedge-alarm command:/usr/local/bin/slack-wedge-alert ``` Where `/usr/local/bin/slack-wedge-alert` is an executable script reading the alarm summary from stdin and posting to your webhook URL. ### Silent Debugging Mode Suppress active notifications while retaining visual markers: ```text # config/wedge-alarm off ``` ### Environment Variable Testing Test the alarm pipeline without sending real notifications: ```sh export FM_WEDGE_ALARM_CHANNEL="command:printf 'Test alarm: %s\n' \"\$1\"" # Restart or reload the away-mode sub-supervisor ``` This prints the alarm summary to stdout, allowing verification of message formatting and timing without external side effects. ## Summary - Configure notification channels in the git-ignored **`config/wedge-alarm`** file, with one directive per line. - Available directives include **`auto`**, **`osascript`**, **`herdr`**, **`command:`**, and **`off`**. - Use **`FM_WEDGE_ALARM_CHANNEL`** for temporary runtime overrides during testing. - The alarm respects **`FM_MAX_DEFER_SECS`** rate limiting and **`FM_WEDGE_ALARM_TIMEOUT_SECS`** execution bounds. - Default behavior falls back to **`auto`** (macOS Notification Center) if the configuration file is absent. ## Frequently Asked Questions ### What happens if the config/wedge-alarm file is missing? If `config/wedge-alarm` does not exist, Firstmate behaves as if the file contained the **`auto`** directive. On macOS, this generates a native notification; on Linux and other platforms, no external alarm fires unless you explicitly configure a `command:` channel. ### How do I test the wedge alarm without sending real notifications? Set the **`FM_WEDGE_ALARM_CHANNEL`** environment variable to a safe command such as `command:echo` or `command:printf` before starting Firstmate. Alternatively, configure `off` in the wedge-alarm file to suppress external notifications while observing the durable marker and tmux flash indicators. ### Can I use multiple notification channels simultaneously? Yes. List multiple directives in `config/wedge-alarm`, one per line. The supervisor attempts each channel sequentially until one succeeds or all are exhausted. For example, you can combine `osascript` for immediate desktop alerts with `command:/path/to/pager` for redundancy. ### Does the wedge alarm work on Linux and Windows, or only macOS? The **`osascript`** directive is macOS-specific. However, **`command:`** works cross-platform, allowing you to integrate with Linux notification daemons, Windows toast notifications via PowerShell, or any custom alerting service. The **`auto`** directive falls back to the durable marker on non-macOS systems unless you provide explicit command directives.