Claude Code Telegram Notifications

Send Telegram notifications when Claude Code sessions complete — automatically, via a Stop hook that fires every time Claude finishes a task.

How It Works

When a Claude Code session ends, a command-type Stop hook reads the session transcript, extracts a summary, and sends it to your Telegram chat. No manual step needed.

Claude Code session ends
  → Stop hook fires (command type)
  → Reads transcript, extracts session title + summary
  → Sends notification to Telegram
  → ✅ You get notified on your phone/desktop

The package provides two entry points:

| Command | Purpose | |---|---| | @nowarzz/claude-telegram | MCP server (stdio transport) — for manual tool calls | | @nowarzz/claude-telegram setup | Registers the Stop hook in ~/.claude/settings.json | | @nowarzz/claude-telegram notify | Called by the Stop hook 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

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 Stop hook

npx -y @nowarzz/claude-telegram setup

This adds the notification hook 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.

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
package.json      Package metadata

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