telegram-integration

Claude Code Telegram Plugin

Bidirectional Telegram messaging for Claude Code with remote permission control.

Features

• Send messages to Telegram - Claude can send updates, progress, and results
• Receive messages from Telegram - Send commands to Claude remotely
• Auto-enter - Messages trigger Claude automatically (no manual Enter needed)
• Remote permission control - Approve/deny tool permissions via Telegram
• Slash command forwarding - Send ;commit on Telegram to run /commit in Claude Code
• Session-specific targeting - Works correctly with multiple Claude windows

Requirements

• Windows only (macOS/Linux support planned)
• Node.js 18+
• Telegram Bot Token (from @BotFather)
• Your Telegram User ID

Installation

As a Plugin

1. Add the marketplace:

   /plugin marketplace add https://github.com/remingtonspaz/claude-code-telegram
   

2. Install the plugin:

   /plugin install telegram-integration:telegram
   

3. Install MCP server dependencies:

   cd ~/.claude/plugins/marketplaces/telegram-integration/mcp-server
   npm install
   

   On Windows: cd %USERPROFILE%\.claude\plugins\marketplaces\telegram-integration\mcp-server

4. Configure credentials in your project (see Setup below)

5. Restart Claude Code

From Source

1. Clone or download this repository into your project directory
2. Run the installer:

   node install.js
   

3. Configure your Telegram credentials (see Setup below)
4. Restart Claude Code

Manual Installation

1. Clone or download this repository
2. Install dependencies:

   cd mcp-server && npm install
   

3. Create the queue directory:

   mkdir ~/.claude-telegram
   

4. Copy .mcp.json.template to .mcp.json and add your credentials
5. Configure hooks in .claude/settings.local.json (see Hooks Configuration below)
6. Restart Claude Code

Setup

1. Create a Telegram Bot

1. Message @BotFather on Telegram
2. Send /newbot and follow the prompts
3. Copy the bot token (looks like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

2. Get Your User ID

1. Message @userinfobot on Telegram
2. It will reply with your user ID (a number like 123456789)

3. Configure Credentials

Add the MCP server to your project's .mcp.json with your credentials:

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["/path/to/claude-code-telegram/mcp-server/server.js"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_bot_token_here",
        "TELEGRAM_USER_ID": "your_user_id_here"
      }
    }
  }
}

Replace /path/to/claude-code-telegram with:

• Source install: The path where you cloned the repo (e.g., ./claude-code-telegram)
• Plugin install: The plugin cache path (check ~/.claude/plugins/)

Each project can have its own .mcp.json with different Telegram credentials.

4. Start Your Bot

Message your bot on Telegram to start the conversation. The bot can only message you if you've messaged it first.

5. Restart Claude Code

Restart Claude Code to load the MCP server and hooks.

6. Verify Installation

Run the status check to verify everything is configured:

node install.js --status

Or check /mcp in Claude Code to see if the telegram server is connected.

Hooks Configuration

The hooks should be configured automatically if you place this plugin in your project. If not, add the following to .claude/settings.local.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "node path/to/hooks/telegram-context.js"
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "node path/to/hooks/permission-telegram.cjs"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "node path/to/hooks/session-start.js"
          }
        ]
      }
    ]
  }
}

Usage

Sending Messages

Claude can send messages to you using the MCP tools:

• telegram_send - Send a text message
• telegram_send_image - Send an image file
• telegram_check_messages - Check for pending messages

Receiving Messages

1. Send a message to your bot on Telegram
2. Claude receives it automatically on the next prompt
3. Messages appear in context as: [Telegram Messages Received] ...

Auto-Enter Feature

When you send a Telegram message, the watcher script automatically:

1. Detects the incoming message
2. Focuses the Claude Code window
3. Sends a keystroke to trigger processing

No need to manually press Enter!

Remote Permission Control