Get a Telegram Ping When Your Claude Code Session Finishes

Claude Code sessions that touch a real codebase can run for a long time. You kick off a refactor, a migration, or a full test-and-fix loop, then switch to something else. An hour later you remember it's still running and go check, only to find it finished forty minutes ago. That gap between "done" and "you noticed" is dead time, and it adds up over a week of long sessions.

The fix is small. Claude Code has a Stop hook that fires a shell command the moment a session ends. Point that command at the Telegram Bot API and you get a phone notification instead of a guessing game. This guide shows the exact call, how to wire it into a hook, and three small Telegram bots that make the notification actually useful once it lands.

The Telegram Bot API Call

Telegram bots send messages through one HTTP endpoint. Create a bot with @BotFather, save the token it gives you, and find your own numeric chat id by messaging @userinfobot. Then the call is a plain POST:

curl -s -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage" \
  -d chat_id="<YOUR_CHAT_ID>" \
  -d text="Claude Code session finished."

That's the full sendMessage method: a chat_id and a text field, both required, sent as POST parameters to https://api.telegram.org/bot<token>/sendMessage. Run the command once from your terminal to confirm the message shows up, then you're ready to hook it in.

Wiring It to the Stop Hook

Claude Code reads hooks from your settings file. Add a Stop hook that runs after a session ends, either in your project's .claude/settings.json or your user-level settings:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST \"https://api.telegram.org/bot$TG_BOT_TOKEN/sendMessage\" -d chat_id=\"$TG_CHAT_ID\" -d text=\"Claude Code finished in $(basename \\\"$PWD\\\")\""
          }
        ]
      }
    ]
  }
}

Keep the token and chat id out of the settings file itself. Export TG_BOT_TOKEN and TG_CHAT_ID in your shell profile instead, so the hook reads them from the environment and nothing sensitive sits in a file you might commit. Once this is in place, every session, whether it runs two minutes or two hours, ends with a message on your phone instead of a tab you keep re-checking.

Beyond the Ping: Bots That Make the Notification Useful

A single "finished" message is a good start, but a working day has more moments than session-end. Three small bots, built for exactly this kind of workflow, cover what comes next. All three answer to an @-mention in any group without being added first, using Telegram's Guest Mode (Bot API 10.0), so you can try one without setting anything up. See the guest-mode guide for how that works.

Nudge: follow-up reminders

A finished session often needs a follow-up: check the deploy in twenty minutes, review the PR after lunch, ping a teammate tomorrow. NudgeRemindBot takes that reminder in plain English, right in the chat where you're already working. Type @NudgeRemindBot tomorrow 9am review the migration PR in any group, even one the bot has never joined, and it shows the exact reminder before you confirm it. A one-minute background check delivers it back to that chat at the right time, in your own timezone.

HabitStreak: a daily shipping streak

Long Claude Code sessions make it easy to lose track of whether you actually shipped something today. HabitStreakProBot tracks a habit like "ship one thing" with a single tap, once a day, and keeps a running streak so you can see the pattern instead of guessing at it. Add the habit with /add ship one thing, then tap it done from the daily prompt or the bot's Mini App board.

WhisperLock: sharing a secret with a teammate

Sessions that touch credentials or staging URLs sometimes need to pass a piece of text to one specific person without pasting it into open chat. WhisperLockBot posts a locked message card into any chat that only the person you tag can open. Type @WhisperLockBot @teammate here's the staging key and everyone else in the chat sees a sealed card; only your teammate (and you) can tap it open. No admin rights needed, and it works inline without adding the bot to the group first.

Putting It Together

None of this requires a server. The Stop hook is a line in a settings file, and the three bots run entirely on Telegram's side. Set the hook once, and every long session ends with a ping instead of a guess. From there, Nudge catches the follow-up, HabitStreak keeps the daily count honest, and WhisperLock handles the one message you don't want sitting in open chat. Small pieces, but they close the gap between when Claude Code finishes and when you actually know it did.

FAQ

Do I need to keep a server running for the Telegram notification to work?

No. The curl call in the Stop hook talks directly to Telegram's API from your own machine when the hook fires. There's no server to host or keep alive.

Will the Stop hook fire if I cancel a session early?

The Stop hook runs when a session ends normally. Check Claude Code's hooks documentation for how it handles an interrupted or killed session in your version, since hook behavior on abnormal exits can change between releases.

Can I send the notification to a group instead of my own DM?

Yes. Add the bot to a group, find that group's chat id, and use it in place of your personal chat id. Group chat ids are negative numbers.

Do Nudge, HabitStreak, and WhisperLock need to be added to my group first?

No. All three answer an @-mention in any chat through Telegram's Guest Mode, so you can try them inline before deciding whether to add them properly. See the guest-mode guide for details.