Notifications not arriving? Work through this list

When a notification doesn't show up, the cause is almost always one of a few things: the hook isn't wired, the agent wasn't restarted, notifications are paused, or the operating system is hiding the banner. anotifier has three commands that tell you which: status, test, and doctor. Start at the top and stop when you find it. For how the Claude Code hooks work in the first place, see the Claude Code notifications guide.

Rather skip the manual setup? One command wires every agent you have installed to desktop toasts, phone push, and Slack, Discord or Telegram:

$ npx anotifier@latest setup

Updated 2026-10-16 · also see the full docs

Step 1: run anotifier status

anotifier status

Tools: each agent shows wired with its events, not wired, not installed, or config error. not wired means setup hasn't patched that agent yet: run npx anotifier@latest setup. Claude Code only counts as installed once ~/.claude/settings.json exists, so start Claude Code once before running setup.
Snooze and Quiet hours: a snooze time, or quiet hours marked (active now), means every channel is silenced on purpose. anotifier snooze off ends a snooze early.
Recent errors: the last 8 hook errors from ~/.anotifier/errors.log, each tagged with what failed (toast:windows, toast:linux, ntfy, webhook, and so on). Failed WSL toasts are logged as toast:wsl since 1.3.0; 1.2.6 and earlier do not log them.
If status itself stops with Config error, ~/.anotifier/config.json is invalid JSON or has a bad value. Fix it, or run setup and let it rebuild the file.

Step 2: send a test

anotifier test           # toast, phone push and bell (plus webhook if enabled)
anotifier test toast
anotifier test ntfy
anotifier test webhook

test sends straight to the channel. It skips the agent's hook, snooze, and quiet hours, which makes the result easy to read:

The test arrives but real notifications don't: the problem is between the agent and anotifier. Restart the agent (a session started before setup doesn't have the hooks), re-run setup, and check snooze and quiet hours in status.
The test fails too: the channel itself is broken. test exits with code 1 and says which one; continue with step 3.

Step 3: run anotifier doctor

anotifier doctor
anotifier doctor --deep

Check	What it looks at
`toast-backend`	The OS toast tool: PowerShell, BurntToast and the execution policy on Windows, `osascript` on macOS, `notify-send` on Linux. Inside WSL, 1.3.0 and later check `wslpath` and a reachable Windows PowerShell; 1.2.6 and earlier check `notify-send`, which WSL toasts never use.
`toast-auth`	macOS only: whether Notification Center allows the app that shows AppleScript banners.
`bell`	Whether your terminal will ring. The VS Code and Windsurf terminals swallow the bell.
`ntfy-config`	Whether a server and topic are set. It does not contact the server; `test ntfy` does.
`webhook-config`	Whether the webhook is set up.
`config`	Whether `~/.anotifier/config.json` is valid.

--deep goes further on macOS and Linux: it sends a real marker notification and reads it back from Notification Center's database (macOS) or dunst's history (Linux). On Windows it reports that deep verification isn't available. doctor exits 1 if any check fails, and --json prints the results with the check names above.

Common causes and fixes

Symptom	Likely cause	Fix
One agent never notifies, `test` works	Hook not wired, or the session started before setup	Run setup, then restart the agent
Codex never notifies	Hooks flag off, stale trust hashes, or running `codex exec`	Re-run setup; use the interactive TUI. See agent hooks
Codex's own alerts only come when you switch away	Codex's built-in notifications default to `notification_condition = "unfocused"`	Set `notification_condition = "always"` under `[tui]`. See Codex notification sounds
Claude Code approval alerts arrive a few seconds late	Claude Code holds its `permission_prompt` notification for about six seconds	Expected. See Claude Code permission notifications
Nothing at all, for a while	Snooze or quiet hours	`anotifier snooze off`; check `quietHours` in the config
Windows: `Toast failed`	PowerShell 7 or BurntToast missing	Install PowerShell 7, then re-run setup. See Windows toast not showing: fixes by symptom
Windows: `Toast sent`, no banner	Do not disturb (Focus Assist)	Settings > System > Notifications. See Do not disturb and Focus Assist on Windows
WSL: `Toast failed`	Windows interop off, or PowerShell not reachable	See how the WSL toast reaches Windows
macOS: `Toast sent`, no banner	Notifications not allowed for Script Editor or your terminal, or a Focus mode	System Settings > Notifications. See macOS & Linux
Linux: `Toast failed`	`notify-send` missing, or no desktop session	Install libnotify; on headless machines use ntfy
Phone stays silent	Not subscribed to the topic, or the topic differs	Compare the ntfy URL in `status` with the app. See ntfy
No bell in VS Code	The integrated terminal ignores the bell	Rely on the toast; `doctor` warns about this. See anotifier in VS Code

Still stuck?

Open an issue on GitHub with the output of anotifier doctor --json and anotifier status, plus the matching lines from ~/.anotifier/errors.log. Remove your ntfy topic first: status prints the full ntfy URL (it only shows a webhook's origin).

For a quick question, or to check whether someone has hit the same thing, ask in the anotifier Discord.

Troubleshooting: common questions

Where does anotifier log errors?

~/.anotifier/errors.log, one JSON object per line with a timestamp, the failing context (such as toast:macos or ntfy), and the message. The file is capped at 128 KB, keeping the newest half when it grows past that. anotifier status shows the last 8 entries.

Does anotifier test respect snooze and quiet hours?

No. test always sends, so you can check a channel while notifications are paused. Real hook events do respect both.

Why does status say Claude Code is not installed?

anotifier looks for ~/.claude/settings.json. Start Claude Code once so it creates the file, then run setup again.

I get notifications, but only a generic message. Why?

anotifier shows what the agent said for Claude Code only, and only on the toast and webhook by default. ntfy stays generic unless you turn on ntfy.richContent, and Codex, Cursor and Gemini CLI always send generic text: my-app: Task complete for Codex and Gemini CLI, and just Task complete for Cursor, whose alerts carry no project name.