How to Configure the Wedge Alarm for Away-Mode Notifications in Firstmate

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 (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:<cmd> 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:

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:

# 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:

# config/wedge-alarm

off

Environment Variable Testing

Test the alarm pipeline without sending real notifications:

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:<cmd>, 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:<cmd> 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}