Troubleshoot

No sessions appear

Start Claude Code or Codex in cmux, then run agent-watchdog status. Check the harnesses, session, cwd, and stale-after settings if expected sessions are absent. A transcript-only session can be monitored without being eligible for terminal messaging. See discovery details.

A metric shows unknown

Codex does not expose prompt-cache expiry or remaining-until-compaction metrics. Unknown context capacity disables percentage-based alerts; it is not zero usage. See Codex metrics.

Settings did not take effect

Run agent-watchdog config validate, restart the daemon, and check for CLI flags overriding your config. Verify that you edited the active --config file. See Apply changes.

An expected message was not delivered

Check the master message switch and the action for that specific trigger. Sessions waiting for input, stale terminal mappings, and missing process or session evidence prevent delivery. See Agent messages and the detailed troubleshooting guide.

Inspect logs and a safe daemon tick

Logs live in ~/Library/Logs/agent-watchdog/ for the installed service. To inspect a foreground tick without sending notifications or terminal messages:

agent-watchdog watch --once --dry-run --verbose

For missing executables, launchd errors, and menu bar issues, use the complete troubleshooting reference.