Push Notifications for Claude Code sessions — Mobile and Desktop

Send a notification to your smartphone whenever Claude Code stops or complete tasks. Get a link to open that session directly into your browser to reply, or directly into the Claude app, if you have it installed.

1 — The problem

Claude mobile app only sends notifications from Claude Code when there is a question regarding your session. But if it stops, needs you to check the progress of the current phase before going to the next one, has a PR for review, or simply completes the task, you never hear about it.

This project fixes two issues I was currently facing with Claude Code:

A. Being away from my desk and having to check how my sessions are going

My sessions often run for a very long amount of time, some can take several hours to complete. If I am not staying close to my computer, Claude Code can stop between steps of the plan and I won't notice until I check it on my phone.

B. Working on too many windows/desktops/projects at the same time.

I am often working on multiple projects at the same time, often with different IDEs and desktops. Despite having a notification sound setup to play whwenever Claude stops, I may not know where it is comming from.

2 — The solution

This repository implements a solution that uses Claude Code hooks to send the push notifications via Webhooks. These notifications are configurable and allow quick access to your session just by clicking on a button. Currently, it only works with the Pushover apps (available for iOS, MacOS, Android and Web/Desktop). However, it is easy to adapt for your own custom app or a 3rd party app that accepts webhooks, such as Telegram, and I do intend to add new adapters over the time.

3 — Available connectors

• Pushover - https://pushover.net/
• Telegram (comming soon)

Please, feel free to send me a PR if you implement a new connector.

4 - Features

Key	Options	Default in the shipped .conf	What it does
Multiple Connectors	pushover · telegram (coming soon)	pushover	Service the notification is delivered through.
Webhooks	bash array of URLs	one URL	Send the notifications to one or more webhooks at the same time.
Custom message title	default · session_name · repository_name · custom	default	Use your session name, repository name or a custom name for the titles.
Custom body messages	last_claude_message · session_name · repository_name · custom · empty	last_claude_message	The notification body can contain a custom message, the last message Claude wrote, the name of the session or the name of the repository.
Session URL	true · false	false	Each notification can have a button directly to the Claude Code session.You can also add the link as an url to the beggining and/or end of the notification body message.

Pushover-specific settings

Key	Options	Default in the shipped .conf	What it does
PUSHOVER_SOUND	pushover default sounds or your custom sound	pushover	Sound played on arrival. Empty leaves the field out. Listen to each one at https://pushover.net/api#sounds; custom sounds: https://blog.pushover.net/posts/2021/3/custom-sounds
PUSHOVER_PRIORITY	-1 low · 0 normal (Pushover's default) · 1 high · 2 emergency	2	-1 no sound or vibration; 0 follows the device settings; 1 bypasses quiet hours; 2 keeps repeating until acknowledged. Unrecognised value → 0.
PUSHOVER_RETRY	seconds, minimum 30	180	Seconds between repeats. Emergency priority only. Below 30 → 30; non-numeric → 180.
PUSHOVER_EXPIRE	seconds, maximum 10800 (3 hours)	7200	How long the repeats go on. Emergency priority only. Above 10800 → 10800; non-numeric → 7200.
PUSHOVER_TITLE_EMOJI	one emoji, or empty	""	Placed in front of the title (🤖 Claude is waiting...). Counts against the 250-character title limit.
PUSHOVER_HTML	true · false	true	Converts Markdown in the body to Pushover HTML and sends html: 1. Link lines in the body become tappable anchors. Needs python3; without it, or with false, the body goes out as plain text and html is left out.

4 — Setup guide

Step 1 - Connector setup

Pushover:

• Create a free Pushover account at https://pushover.net/
• Log-in, then scrolldown to the end of the page and click on Your Applications - Create an Application/API Token; Enter a name and leave all the other default options.
• Back to the dashboard initial page, find Your Webhooks and click on Create a Webhook. Give it a name and click on Save Settings.
• After the page reloads, the webhook URL will be displayed at the top of the page. Copy it.
• Install the apps for Android, iOS and/or Desktop. Make sure you login with your account.
• Take a moment to go through the notify-claude.conf file and see all the available options.

Step 2 - Download the repository files

• Clone this repository or click here to download the files.
• The files can be anywhere in your computer. I recommend a location you are sure Claude Code has access to.
• Open notify-claude.conf. Find the configuration WEBHOOK_URLS, enter the url of the webhook we created during Step 1. Save the file.
• Run the script in your CLI to send a test message:

NOTIFY_TITLE="notify-pushover test" \
NOTIFY_BODY='Hi, this is a test message' \
/path/to/notify-claude.sh <<< '{"session_id":"test","transcript_path":"","cwd":"'"$PWD"'"}'

• Find your Claude Code settings.json. You can set this up on your global file or locally for a single project. If you do not know how to find this file, click here.
• Setup the hooks session of the settings.json, like this:

{
  "model": "",
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/notify-claude.sh",
            "async": true
          }
        ]
      }
    ],
    "TaskCompleted": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/notify-claude.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

Note: do not forget to update the command path to the notify-claude.sh script.

Everything should be working now. Enjoy your freedom!