DEV Community

gtapps
gtapps

Posted on

Claude Code PushNotification tool: what it does and how to use it

#claudecode #claude #ai #programming

PushNotification is a native Claude Code tool you can call to send PushNotification to your phone or Claude app.

The obvious use case is long-running tasks:

"Run the full test suite, fix what you can, and notify me using the PushNotification tool when the suite is green or blocked.""

But the more interesting cases are background workflows:

Useful examples:

  • notify when a build finishes
  • notify when a monitor sees a production-like error in logs
  • notify when a scheduled task finds something
  • notify when Claude is blocked on a human decision
  • notify when a remote/headless session needs attention
  • notify when a channel integration failed and the agent could not DM you
  • notify when a morning brief or weekly review is ready

This is especially useful with Monitor Tool, /loop, Crons.

How it works

  1. You enable mobile push in /config with "Push when Claude decides."
  2. Activate remote-control for mobile push through the Claude app.
  3. Ask for it directly in a prompt or set a rule in CLAUDE.md, for example: "run the tests and notify me with the PushNotification tool when they finish."

How I wire it

On my Claude Code Always-on Agents (claude-code-hermit plugin), the notification policy is:

  • if a real two-way channel is reachable, send the message there first
  • if no channel is configured, use PushNotification
  • if a configured channel is broken, use PushNotification as fallback
  • never rely on push as the only record
  • keep push messages short, one-line, actionable, and low-frequency

That keeps the signal clean. Push should not duplicate every Discord/Telegram message. It should cover the cases where the normal path is absent, broken, or too slow.

Best practices

Keep the message short:

CI failed on api-tests: 3 auth regressions. Open session for details.

Put the actionable bit first:

Decision needed: choose migration strategy before Claude edits schema.

Do not push for routine progress. Push for state changes: done, blocked, failed, needs decision.

If you need to answer Claude, use Remote Control or a two-way channel. Push only gets your attention.

Links

Tools reference: https://code.claude.com/docs/en/tools-reference

My take: PushNotification is a small tool, but it changes the workflow. Claude Code no longer has to sit silently in a terminal while you periodically check whether it finished. It can now tap you when the work is done, blocked, or worth opening again.

Top comments (0)