Skip to content
agent-watchdog

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 is monitored like any other, but its lifecycle is unknown. 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.

Subscription usage is unavailable

Session monitoring and subscription usage have separate sources. An empty usage card does not mean your subscription has no allowance remaining. Start with the usage setup checklist and read the provider diagnostic in the popover or Settings.

Provider / diagnostic What to do
Codex: spawn_failed or “spawn failed” Install Codex, then rerun agent-watchdog install from a shell where command -v codex finds it. If an explicit openai-codex-path already exists, correct it in Settings and restart the daemon.
Codex: missing_login or “missing login” Sign in to Codex with the subscription account in the configured codex-home. Sign-in on another machine does not configure this machine.
Codex: closed_early or “closed early” Codex exited before returning usage. In Settings → OpenAI / Codex usage, check the executable path. If it points into cmux-cli-shims or to cmux-codex-wrapper, select the actual Codex executable, save, and restart the daemon. Otherwise check that Codex itself starts normally.
Codex: unsupported_auth or “unsupported auth” Use a subscription login that reports rate limits; an API-key login does not provide subscription allowance data.
Claude: source_not_bound or “source not bound” Rerun the installer to configure the bridge. If it reports settings it cannot change, follow the manual bridge instructions linked below.
Claude: windows_absent, “windows absent”, or no readings yet Open a signed-in Claude Code session with a supported version and subscription. Verify its active status-line command includes the bridge; project-level settings can override user settings.
Claude: bridge_renderer_error or “bridge renderer error” Your own status-line command failed or ran past anthropic-usage-renderer-timeout (5s by default). Raise that setting if the command is slow on a cold start; the usage sample is still saved.
Claude: probe_not_found Install Claude Code, or set anthropic-claude-path in Settings to its executable, then restart the daemon. The daemon looks in ~/.local/bin/claude, then PATH.
Claude: probe_report_missing or probe_limits_missing Sign in to Claude Code with a subscription account on this machine. Until the usage command returns allowance rows, the popover shows the status-line bridge instead.
Claude: probe_exit_error Run the usage command from the Claude usage probe in a terminal. A launch agent has no shell PATH, so a Claude Code installed through a Node package manager may not start; point anthropic-claude-path at a native install.
Claude: probe_malformed_output Claude Code changed its experimental usage output. The status-line bridge stays in use; report the Claude Code version.
Either provider: timeouts or unavailable source Check the provider tool’s own sign-in/network status and the daemon logs. The daemon retries collection; the popover’s Refresh only rereads local status.

Installation keeps explicitly disabled monitoring and custom paths. Check those settings before reinstalling. Automatic discovery skips cmux terminal wrappers, but a wrapper path saved by an earlier install remains an explicit setting and must be corrected in Settings. Claude automatic setup can be skipped when --no-setup-usage is passed, when no Claude configuration directory exists, or when its settings are malformed, symlinked, or explicitly disabled. Installer output identifies those cases. See manual Claude setup.

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 notification did not appear

Each threshold fires once per crossing and re-arms only after usage drops below it again, so a session already above the threshold when the daemon started does not alert twice. Check that osascript (Script Editor) notifications are allowed in System Settings. See the detailed troubleshooting guide.

Generate handoff is unavailable

Hover the button for the reason. A handoff is generated only for an idle session: a Codex session found only by the transcript scan, or a Claude Code session that claude agents does not list as idle, is refused as busy. When the reason names the command-line tool, set openai-codex-path in Settings for Codex, or install Claude Code where PATH or ~/.local/bin finds it. See Generating a handoff.

The daemon seems stuck after an upgrade

If the daemon seems stuck after an upgrade, run agent-watchdog install again (or check launchctl print gui/$(id -u)/com.wholeclove.agent-watchdog for ProcessType). Earlier releases installed the daemon with ProcessType Background, which lets macOS throttle its disk reads until it stops writing status. Reinstalling rewrites the plist with Standard and reloads it. See 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:

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

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