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.