🤖 Claude Telegram Notifier

Get Telegram notifications when Claude Code finishes a task or needs your attention.

Never stare at your terminal again — let Claude ping you on Telegram when it's done.

How It Works

This tool plugs into Claude Code's hooks system. When Claude finishes responding (Stop event) or needs your input (Notification event), it sends a formatted message to your Telegram chat.

✅ Claude Code — Task Complete

📁 Project: MyApp
🕐 Time: 14:30:25

💬 Summary:
I've completed the refactoring of the authentication module...

Quick Start

1. Install

npm install -g cc-telegram-notifier

Or use directly with npx (no install needed):

npx cc-telegram-notifier setup

2. Configure Telegram Bot

claude-notify setup

This interactive wizard will:

• Guide you to create a Telegram bot via @BotFather
• Auto-detect your Chat ID
• Send a test message to verify everything works

3. Enable for a Project

Navigate to your project directory and run:

cd your-project
claude-notify init

This installs hooks into your project's .claude/settings.json.

4. Done!

Start (or restart) Claude Code. You'll receive Telegram notifications automatically.

CLI Reference

| Command | Description | |---|---| | claude-notify setup | Configure Telegram bot credentials (one-time) | | claude-notify init | Install hooks in the current project | | claude-notify test | Send a test notification to Telegram | | claude-notify status | Show configuration and hook status | | claude-notify uninstall | Remove hooks from the current project | | claude-notify help | Show help message |

Notification Types

✅ Task Complete (Stop event)

Sent when Claude finishes responding to your prompt. Includes:

• Project name
• Timestamp
• Summary of Claude's last message (truncated to 500 chars)

⚠️ Attention Needed (Notification event)

Sent when Claude needs your input. Types include:

• 🔐 Permission Prompt — Claude needs permission to run a command
• 💤 Idle — Claude is waiting for your input
• ❓ Question — Claude has a question for you

Configuration

Credentials are stored in ~/.claude-telegram-notifier.json:

{
  "botToken": "123456:ABC-DEF...",
  "chatId": "987654321",
  "enabledEvents": ["Stop", "Notification"]
}

Hooks are installed per-project in .claude/settings.json.

What Gets Added to Your Project

The init command adds the following to your .claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npx cc-telegram-notifier notify-stop"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npx cc-telegram-notifier notify-attention"
          }
        ]
      }
    ]
  }
}

Note: If you already have other hooks configured, the notifier hooks are appended — your existing hooks are preserved.

Creating a Telegram Bot

If you haven't created a Telegram bot yet, follow these steps:

1. Create the Bot

1. Open Telegram and search for @BotFather
2. Send /newbot
3. Follow the prompts — give your bot a name (e.g., "Claude Notifier") and a username (e.g., my_claude_notifier_bot)
4. BotFather will give you an API token like 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

2. Find Your Chat ID

1. Open a chat with your new bot on Telegram
2. Send any message (e.g., "hello")
3. Run claude-notify setup — it will auto-detect your Chat ID

Manual method: Visit this URL in your browser (replace YOUR_TOKEN):

https://api.telegram.org/botYOUR_TOKEN/getUpdates

Look for "chat":{"id":123456789} in the response.

3. Run Setup

claude-notify setup

Paste your bot token when prompted, and the wizard will handle the rest.

Checking Status

To see if notifications are active for the current project:

claude-notify status

Example output:

╔══════════════════════════════════════════════════════════╗
║         🤖 Claude Telegram Notifier — Status           ║
╚══════════════════════════════════════════════════════════╝

  📋 Config: /Users/you/.claude-telegram-notifier.json
  🔑 Bot Token: 12345678...9abc
  💬 Chat ID: 987654321
  📡 Events: Stop, Notification

  📁 Project: /Users/you/projects/my-app
  ✅ Stop hook: Installed
  ✅ Notification hook: Installed

Tips

• Multiple projects: Run claude-notify init in each project where you want notifications. The Telegram credentials are shared globally.
• Team usage: If your team wants notifications, each person runs claude-notify setup with their own bot. The .claude/settings.json can be committed to version control if everyone uses the same npm package.
• Restart required: Claude Code snapshots hooks at startup. After running init or uninstall, restart Claude Code for changes to take effect.
• Test anytime: Run claude-notify test from anywhere to verify your Telegram connection is working.

Git Considerations

The .claude/settings.json file is typically project-specific. You have two options:

1. Commit it — Everyone on the team gets notifications (they each need their own claude-notify setup)
2. Use .claude/settings.local.json — For personal overrides (this file is typically git-ignored)

If you want notifications only for yourself without affecting the team, you can manually add the hook entries to .claude/settings.local.json instead.

Troubleshooting

"Not configured" error

Run claude-notify setup to configure your Telegram bot credentials.

Not receiving notifications

1. Run claude-notify test to verify Telegram connectivity
2. Run claude-notify status to check hook installation
3. Make sure you restarted Claude Code after running claude-notify init

Hooks not firing

Claude Code snapshots hooks at startup. If you modified settings while a session was running, restart Claude Code or use the /hooks command inside Claude Code to reload.

Bot not sending messages

• Ensure you've sent at least one message to your bot on Telegram
• Verify your Chat ID is correct with claude-notify status

Requirements

• Node.js 18 or later
• Claude Code with hooks support
• Telegram account

License

MIT