Agent messages and handoffs

Notifications are the default

On a fresh installation, message-agents is false and both action lists are notify. You can receive alerts without allowing terminal messages. Changing a threshold or upgrading does not opt you into handoffs. Existing explicit settings remain in effect until you change them.

Opt into a specific trigger

Two settings are required: enable the master message-agents switch, then choose handoff (or stop for critical context) in the relevant action list. The master switch alone does not select an action. For critical-context handoffs only, merge these settings into your config:

{
  "message-agents": true,
  "on-critical": ["notify", "handoff"],
  "on-cache-expiry": ["notify"]
}

For Claude cache-expiry handoffs, separately add handoff to on-cache-expiry. Codex has no cache-expiry trigger. A foreground example:

agent-watchdog watch --message-agents --on-critical notify,handoff

Validate and restart after editing the file, or use the settings window’s restart action. CLI flags override the file, including action lists. Configure alerts explains how to apply settings. Try a throwaway session before enabling messages for ongoing work.

Turn messages off

Set message-agents to false to disable all terminal messages. To disable only one trigger’s handoffs, remove handoff from that trigger’s action list; use ["notify"] to retain its notifications. Save, validate, and restart the daemon. Remove conflicting CLI overrides from launch arguments or foreground commands. Once the restarted daemon reads the new settings, pending requests for a disabled action cannot send reminders.

What to expect

Messages start with [agent-watchdog]. The daemon verifies the target session, process, and terminal lifecycle before typing. A session waiting for input is not interrupted; delivery can be deferred. A critical handoff already asks the agent to stop, so selecting both stop and handoff sends only the handoff.

The agent writes the handoff file; watchdog requests it and checks whether it appears. It may remind the agent while the request remains enabled and pending. Open available handoffs from the menu bar. See the handoff format and paths and delivery safety checks for details.