Skip to content
agent-watchdog

Configure alerts

Start with notifications

A fresh installation monitors Claude Code and Codex and sends notifications. The daemon never types into an agent’s terminal; when a session crosses the critical threshold or its prompt cache is about to expire, the notification asks you to have the agent write a handoff, which you can also request from the session’s row in the menu bar popover. Open Settings from the gear in the popover’s header, or edit ~/.config/agent-watchdog/config.json:

{
  "warn-context": 35,
  "critical-context": 75,
  "cache-lead": "10m"
}

Merge changes into your existing file; do not replace other preferences. An upgrade preserves explicit settings.

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.

Subscription usage

The installer configures subscription usage for enabled providers. In Settings, OpenAI / Codex usage and Anthropic / Claude usage control monitoring separately from notifications. If you enable a provider after installation, run agent-watchdog install again to configure its source, keeping your custom --config argument if any.

Codex uses your signed-in subscription account. Set openai-codex-path to an absolute executable path when automatic discovery cannot find your installation. Claude requires a signed-in session to deliver a first status-line sample; its historical readings do not support allowance notifications. See Unavailable usage for the setup diagnostics.

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.