Repository navigation
Troubleshooting
| Card shows | Meaning | Fix |
|---|---|---|
| Waiting for first refresh… | No poll has completed yet. | Wait, or click Refresh. |
| Not logged in | No matching keychain entry for that config dir. | Run claude and /login for that profile, or remove the account. |
| Keychain access denied | A real keychain consent failure. Cached negatively for 30 minutes. | Usually clears itself. If not, check Keychain Access for a Claude Code-credentials… item with a broken access list. |
| Login token expired, open a Claude Code session for this profile | Local Claude account, two consecutive 401s. | Run claude with that CLAUDE_CONFIG_DIR and let it refresh. /login only if that does not help. |
| Login token expired, run codex in this profile | Codex account, two consecutive 401s. | Run codex with that CODEX_HOME. codex login only if that does not help. |
| Credentials expired (remote, with Paste credentials…) | The refresh failed, often the rotation race. | Paste a fresh JSON from the source machine. See Accounts. |
| Rate limited until HH:MM | The usage endpoint returned 429. Backoff is 3 → 6 → 12 → 15 minutes, reset by any success. | Nothing to do. If every account stays limited beyond ~15 minutes, make sure no other heavy poller uses the same token. |
| Last refresh failed: … | The last poll failed, but a previous good snapshot is still shown. | Check the error text; for transport errors, check your network. |
Discovery only adds a directory with usable credentials: a keychain entry for Claude, a readable ChatGPT token in auth.json for Codex (API-key-only logins are skipped). Add other locations with Add Claude Account… or Add Codex Account….
Check Settings → Alerts for the notification authorization status and fix it in System Settings → Notifications. ntfy and toast alerts do not depend on that permission.
You probably answered the Gatekeeper dialog with Move to Trash. Reinstall and clear quarantine first. Settings and accounts are kept.
Everything logs to unified logging under subsystem com.roy.agentsmonitor (categories poll, alerts, http, credentials, notify). Tokens and credential payloads are never logged. Account display names appear in your local log only.
# live tail
/usr/bin/log stream --predicate 'subsystem == "com.roy.agentsmonitor"' --level debug
# recent history
/usr/bin/log show --last 2h --info --debug --predicate 'subsystem == "com.roy.agentsmonitor"'Alert decisions are logged as:
eval <account>/<limit>: <pct>% level=<new> stored=<old> sameWindow=<bool> fire=<bool>
That is enough to reconstruct why an alert did or did not fire. The de-dupe memory lives in defaults under AgentsMonitor.alertMemory; delete that key to force a full re-alert.
Open an issue at github.com/roypadina/AgentsMonitor/issues with the relevant log lines (no tokens are in them).
