Claude Code Telegram Notifications

Send Telegram notifications when a Claude Code session completes, needs your permission, or asks you a question — automatically, via Stop, Notification, and PreToolUse hooks.

📋 See CHANGELOG.md for the release history.

How It Works

Three Claude Code hooks send messages to your Telegram chat, with no manual step:

Session ends (Stop hook)
  → Reads transcript, extracts title + summary → ✅ Task Complete

Claude needs tool/permission approval (Notification hook, permission_prompt)
  → Sends the approval request straight to you → 🔐 Permission needed

Claude asks you a question (PreToolUse hook, AskUserQuestion)
  → Pings you with the question text → ❓ Claude is asking

Other Claude Code notifications (anything that isn't a permission prompt) arrive as a 🔔 "Claude is waiting" message instead.

The package provides two entry points:

| Command | Purpose | |---|---| | @nowarzz/claude-telegram | MCP server (stdio transport) — for manual tool calls | | @nowarzz/claude-telegram setup | Registers Stop + Notification + PreToolUse hooks in ~/.claude/settings.json | | @nowarzz/claude-telegram notify | Called by the Stop / Notification / PreToolUse hooks to send the notification |

Install (for users)

Prerequisites

• Claude Code CLI installed
• A Telegram bot token and chat ID

Step 1: Create a Telegram bot

1. Message @BotFather on Telegram
2. Send /newbot and follow the prompts
3. Copy the bot token (format: 123456:ABC-DEF...)

Step 2: Get your chat ID

• For groups/channels: Add the bot to the group, then visit: https://api.telegram.org/bot<TOKEN>/getUpdates Send a message in the group, then refresh — the chat.id field is your chat ID (usually a negative number for groups).
• For personal notifications: Send /start to your bot, then use the same getUpdates URL.

Step 3: Add the MCP server

claude mcp add telegram -s user \
  -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF \
  -e TELEGRAM_CHAT_ID=-1001234567890 \
  -- npx -y @nowarzz/claude-telegram

You can use any scope (-s user, -s project, or -s local) — the notifier reads credentials from all of them.

Note: Credentials are matched by the server's command/args content containing claude-telegram, so a custom command must include that substring.

This registers the MCP server in Claude Code's config. The -s user flag makes it available globally across all projects. The -e flags pass your credentials.

Step 4: Setup the hooks

npx -y @nowarzz/claude-telegram setup

This adds the Stop, Notification, and PreToolUse hooks to ~/.claude/settings.json. It's idempotent — safe to run multiple times. It also cleans up old prompt-type hooks from previous versions.

Step 5: Done

Next time Claude Code finishes a session, you'll get a Telegram notification like:

✅ Task Complete: Implement user auth

📁 Workspace: /home/dev/my-project

📝 Summary:
Added JWT-based authentication with login and signup endpoints.
Created auth middleware for protected routes. All tests passing.

When Claude needs to approve a tool, you'll instead get:

🔐 Permission needed

📁 Workspace: /home/dev/my-project

📝 Claude needs your permission to use Bash

When Claude asks you a question (e.g. via AskUserQuestion), you'll get:

❓ Claude is asking

📁 Workspace: /home/dev/my-project

📝 Do you want to merge this to the main branch?

Development (for contributors)

Prerequisites

• Node.js 20+
• Yarn 4+

Setup

git clone <repo-url> @nowarzz/claude-telegram
cd @nowarzz/claude-telegram
yarn install
yarn build

Project structure

src/
  notify.ts    CLI entry point — setup, notify, help (built-in Node.js only)
  server.ts    MCP server — tool + prompt registration (imports MCP SDK)
dist/          Compiled output

The split is intentional: the Stop hook runs notify.js which only uses built-in Node.js modules (fs, path, os, fetch). This avoids MODULE_NOT_FOUND errors when the hook runs outside Yarn PnP or before npm install completes.

Running locally

# MCP server
yarn start

# Setup command
yarn node dist/notify.js setup

# Test notify with a real transcript
echo '{"transcript_path":"/path/to/transcript.jsonl","cwd":"/my/workspace"}' \
  | TELEGRAM_BOT_TOKEN=xxx TELEGRAM_CHAT_ID=xxx \
  yarn node dist/notify.js notify

Testing with real credentials

Create a .env file:

cp .env.example .env
# Edit .env with your bot token and chat ID

Then test:

export $(grep -v '^#' .env | xargs)
TRANSCRIPT=$(find ~/.claude/projects -name "*.jsonl" -type f | head -1)
echo "{\"transcript_path\":\"$TRANSCRIPT\",\"cwd\":\"$(pwd)\"}" \
  | yarn node dist/notify.js notify

Publishing (for maintainers)

One-time setup

npm login

Publish a new version

# 1. Bump version in package.json
# 2. Build and publish
yarn build
npm publish

The prepublishOnly script runs yarn build automatically. Only dist/ and package.json are included in the package (controlled by files and .npmignore).

What gets published

dist/notify.js    CLI entry point (bin)
dist/server.js    MCP server
dist/lib.js       Pure helpers imported by notify.js
package.json      Package metadata

Source files, docs, and config are excluded via .npmignore.