🟠 Claude Telegram

Telegram bridge for Claude Code — notifications, approvals, and remote control from your phone.

---

What it does

Claude Telegram connects your Claude Code CLI sessions to Telegram, so you can:

• 🔔 Get notified when Claude Code needs approval, hits an error, or finishes a task
• ✅ Approve or reject tool executions from your phone
• 💬 Send messages to active Claude Code sessions from Telegram
• 📊 Monitor multiple sessions at once

All with Claude's signature 🟠 aesthetic.

How it looks

Approval request

🟠 Claude Code

📂 polybot-arbitrage
🔧 Bash › pip install requests

━━━━━━━━━━━━━━━━━━━━

[✅ Aprobar]  [❌ Rechazar]  [🔍 Detalle]

Session completed

🟠 Claude Code · Listo ✨

📂 polybot-arbitrage
⏱️ 4m 23s  ·  📝 8 archivos  ·  ✅ 5 aprobados

💬 Implementé el endpoint de webhook
   y actualicé los tests.

Multiple sessions

🟠 Claude Code · 3 sesiones activas

1️⃣ 📂 polybot-arbitrage · ⏱️ 2m · 🔄 trabajando
2️⃣ 📂 arbitrage · ⏱️ 8m · ⏸️ esperando aprobación
3️⃣ 📂 bts-army-hub · ⏱️ 1m · ✅ completado

Quick Start

1. Create a Telegram bot

Talk to @BotFather on Telegram and create a new bot. Save the token.

📖 Detailed instructions: docs/setup-telegram.md

2. Install

git clone https://github.com/jparedesDS/claude-telegram
cd claude-telegram
pip install .

3. Configure

claude-telegram install

This will:

• Ask for your bot token and chat ID
• Save config to ~/.claude/telegram/.env
• Add hooks to ~/.claude/settings.json

4. Start

claude-telegram start

That's it! Open any Claude Code session and you'll start receiving notifications on Telegram.

Commands

Command	What it does
/start	Verify connection
/help	List commands
/status	Show active sessions
/mute	Silence notifications
/unmute	Re-enable notifications
/mute 30m	Mute for 30 minutes
/ask 1 message	Send message to session #1
any text	Send to active session

How it works

Claude Code ──hooks──▶ HTTP POST ──▶ Telegram Bot ──▶ Your phone
    ◀──── response ◀──── localhost:7483 ◀──── ✅/❌ buttons

1. Claude Code's hooks system sends HTTP requests to a local server
2. The bot formats messages with 🟠 Claude aesthetic and sends them to Telegram
3. For approvals, the HTTP connection stays open until you tap ✅ or ❌
4. If the bot isn't running, Claude Code works normally (graceful degradation)

Supported hooks

Hook	Trigger	Blocking
SessionStart	New Claude Code session	No
PreToolUse	Bash, Edit, Write, NotebookEdit	Yes — waits for approval
PostToolUseFailure	Any tool failure	No
Notification	Claude needs attention	No
Stop	Session ended	No

Configuration

All config lives in ~/.claude/telegram/.env:

TELEGRAM_BOT_TOKEN=your-token
TELEGRAM_CHAT_ID=your-chat-id
CLAUDE_TG_PORT=7483              # HTTP server port
CLAUDE_TG_APPROVAL_TIMEOUT=120   # Seconds before timeout (default: 2 min)

CLI

claude-telegram install   # Set up hooks and config
claude-telegram start     # Start the bot
claude-telegram stop      # Stop the bot
claude-telegram status    # Check if bot is running

Requirements

• Python 3.11+
• Claude Code CLI installed
• A Telegram account

Support

License

MIT