Claude-Telegram Bridge 🤖💬

A seamless 2-way communication system between Claude Code and Telegram, enabling remote interaction with your AI assistant from anywhere in the world.

🌟 Features

• 📱 Real-time Notifications: Get Telegram messages whenever Claude completes a response
• 🔄 2-Way Communication: Reply from Telegram to continue conversations seamlessly
• 📝 Markdown Formatting: Preserves Claude's formatting (bold, italic, code, headers)
• 🔍 Session Management: Unique session IDs prevent multi-session conflicts
• 📊 History Viewing: Review Telegram conversations with show-telegram command
• 🚀 Always Running: Background listener works immediately or years later
• ⚡ Auto-start Support: macOS Login Items integration for automatic startup on login
• 🎯 Simple & Clean: Minimal setup, no complex dependencies
• 📂 Git Integration: See what code changed during each session automatically
• 🔍 Detailed Diffs: View complete git changes with show-changes command
• 🧹 Auto-cleanup: Automatically removes old sessions (30+ days) to maintain performance

🎬 Quick Demo

Terminal: claude "Help me debug this Python code"
Telegram: 🤖 Session abc123 - my_project (14:30)

         📂 Recent changes:
         ✏️ src/app.py (modified)
         ➕ tests/test_fix.py (added)

         I'll help you debug your Python code...
         [Claude's formatted response]

         Reply: abc123:your message

You: abc123:what about line 42?
Terminal: [Session continues automatically with your question]

Later: show-changes abc123 --full  # See complete diff

🚀 Quick Start

Prerequisites

• Python 3.7+
• Claude Code CLI installed and configured
• Telegram account
• macOS or Linux (Windows support coming soon)

Installation

1. Clone the repository

   git clone https://github.com/blueman82/claude-telegram-bridge.git
   cd claude-telegram-bridge

2. Create your Telegram bot

   • Message @BotFather on Telegram
   • Use /newbot command
   • Save your API token

3. Run the automated setup script

   chmod +x setup.sh
   ./setup.sh

   The script will:

   • Install Python dependencies
   • Copy scripts to correct locations
   • Configure your Telegram bot
   • Add convenient aliases to your shell
   • Offer auto-start setup (macOS Login Items) or manual start option

   Or follow manual setup instructions if you prefer

4. Start using!

   claude "Hello from Claude-Telegram!"

📖 Documentation

• Full Setup Guide - Detailed installation and configuration
• Troubleshooting - Common issues and solutions
• Security Notes - Best practices
• Testing Guide - Running tests and contributing

🏗️ Architecture

[Claude] → [Hook] → [Telegram] → [You]
    ↑                               ↓
    └────── [Listener] ←────────────┘

Flow:

1. Claude CLI finishes → triggers Stop Hook
2. Stop Hook → sends notification to Telegram Bot
3. Telegram Bot → delivers message to your phone
4. You reply with session_id:message
5. Listener Service → picks up reply
6. Listener → runs claude --resume to continue session

Components

• Stop Hook (stop.py): Runs after each Claude response, sends notifications
• Listener Service (telegram_listener.py): Monitors for Telegram replies
• Show History (show-telegram.py): View conversation history

💡 Usage Examples

Basic Conversation

# Start a session
claude "Explain quantum computing"

# Reply from Telegram
# 81950c:can you give a simpler explanation?

View Conversation History

# From terminal/bash shell:
show-telegram 81950c

# From within active Claude Code session:
!show-telegram 81950c

View Git Changes

# From terminal/bash shell:
show-changes 81950c              # Files changed during session
show-changes 81950c --full       # Complete diff with code changes

# From within active Claude Code session:
!show-changes 81950c             # Files changed during session
!show-changes 81950c --full      # Complete diff with code changes

# Lists available sessions if ID not found
show-changes invalid_id

Check System Status

The setup script adds these aliases to your shell:

# Start the background listener
telegram-start

# Stop the listener
telegram-stop

# Check if listener is running
telegram-status

# View conversation history (from terminal)
show-telegram <session_id>

# View git changes for a session (from terminal)
show-changes <session_id>
show-changes <session_id> --full  # Full diff

# Note: Use ! prefix when inside Claude Code sessions:
# !show-telegram <session_id>
# !show-changes <session_id>

Important: After running setup.sh, reload your shell:

# For zsh (macOS default)
source ~/.zshrc

# For bash
source ~/.bashrc

# Or just open a new terminal

🔧 Configuration

Environment Variables

Create ~/.claude/.env:

TELEGRAM_API=your_bot_token_here

Chat ID

Store your Telegram chat ID in ~/.claude/.chat_id:

echo "YOUR_CHAT_ID" > ~/.claude/.chat_id

🐛 Known Issues

• Markdown parsing conflicts with special characters in Claude's responses
• Stop hook only triggers when Claude finishes responding
• Replies must use exact format: session_id:message
• Shell detection may add aliases to wrong config file (zsh users may need to copy from ~/.bashrc to ~/.zshrc)

🎆 Features in Detail

Session Management

• Each Claude session gets a unique 6-character ID
• Sessions persist across terminal and Telegram
• Multiple concurrent sessions supported without conflicts
• Session history stored in ~/.claude/.sessions

Formatting Support

• Bold text preserved from Claude's markdown
• Italic text converted properly
• Code blocks maintained in monospace
• Headers converted to bold for Telegram compatibility
• Lists converted to bullet points

Hook Safety

• Setup script preserves existing Claude hooks
• Appends our stop hook without overwriting others
• Non-destructive configuration updates
• Checks for existing configuration before modifying

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Run tests to ensure everything works:

   python -m venv test_env && source test_env/bin/activate
   pip install -r requirements-test.txt
   python tests/test_stop_hook.py && python tests/test_git_integration.py

4. Commit your changes (git commit -m 'Add some AmazingFeature')
5. Push to the branch (git push origin feature/AmazingFeature)
6. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built for Claude Code by Anthropic
• Telegram Bot API for reliable messaging
• The Claude community for inspiration

📬 Support

• Open an issue for bugs or feature requests
• Check existing issues before creating new ones
• For setup help, see the troubleshooting guide

🚦 Status

---

Made with ❤️ for seamless AI communication

Never lose context again - continue your Claude conversations from anywhere!