Configure alerts

Start with notifications

A fresh installation monitors Claude Code and Codex and sends notifications without typing into their terminals. Open Settings… in the menu bar, or edit ~/.config/agent-watchdog/config.json:

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

Merge changes into your existing file; do not replace other preferences. An upgrade preserves explicit settings. To request handoffs, follow Agent messages.

Choose thresholds

warn-context defaults to 35 and critical-context to 75 percent. Keep the critical threshold above warning and below your agent’s compaction point. Claude cache-expiry notifications apply only to idle sessions meeting cache-min-context; Codex does not report prompt-cache expiry. See the generated option reference for defaults, command scope, and harness applicability.

Apply changes

Validate your file before restarting:

agent-watchdog config validate
launchctl kickstart -k gui/$(id -u)/com.wholeclove.agent-watchdog

The settings window offers a restart after saving. A running daemon reads settings at startup. Command-line flags override the config file, and list flags replace the file’s list. If a change seems ignored, inspect the launch agent’s arguments and any foreground watch command for overrides. See config precedence for custom files, validation errors, and migration details.

Limit monitored sessions

Use harnesses to select Claude Code, Codex, or both. Use repeatable session and cwd filters to narrow a run. Unknown context capacity cannot trigger a percentage alert; only configure an override when you know the actual capacity.