Telegram ↔ Claude Code Bridge

A portable, template-based installation system that creates a bi-directional bridge between Telegram and Claude Code CLI sessions.

Features

• Multi-Server Single-Group: All servers share ONE Telegram group with server-prefixed topics [ServerName]
• Automatic Topic Management: Auto-creates Telegram topics for each Claude session/conversation
• Bi-directional Communication: Send messages to Claude from Telegram, receive notifications in Telegram
• Multi-Session Support: Manage multiple Claude Code sessions from a single Telegram group
• Auto-Restart on Reboot: Systemd integration keeps everything running after server restarts
• Conversation ID Tracking: Automatically updates topic mappings when conversations restart
• Template-Based Installation: Zero hardcoded values - fully portable across servers
• Python stdlib Only: No external dependencies for core functionality
• Simple Setup: No authentication required - just bot token and group chat ID

Quick Start

Installation via NPM (Recommended)

npm install -g telegram-claude-bridge

Setup Modes

Interactive Mode (Recommended)

telegram-claude-bridge setup

Guided installation with prompts for each configuration option.

Non-Interactive Mode

telegram-claude-bridge setup --non-interactive \
  --bot-token "YOUR_BOT_TOKEN" \
  --chat-id "-1001234567890" \
  --server-name "Production" \
  --enable-systemd yes

Perfect for CI/CD pipelines and automation.

Prerequisites

• Linux server (Ubuntu, Debian, Amazon Linux, etc.)
• Telegram bot token (from @BotFather)
• Telegram group with forum topics enabled
• Claude Code CLI
• tmux installed

Manual Installation (Without NPM)

# Clone repository
git clone https://github.com/yourusername/telegram-claude-bridge
cd telegram-claude-bridge

# Run installation wizard
./install.sh

The installer will:

1. Validate your Telegram bot token
2. Detect running tmux sessions
3. Configure Claude Code hooks
4. Set up auto-restart (optional)
5. Create all necessary files

What You'll Need

1. Telegram Bot Token

   • Talk to @BotFather
   • Create new bot with /newbot
   • Copy the token (format: 123456789:ABC-DEF...)

2. Telegram Group Chat ID

   • Create a new group
   • Add your bot to the group
   • Make it an admin
   • Enable "Topics" in group settings
   • Get the chat ID:

     # Send a message in the group, then:
     curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates" | grep chat.*id

   • Format: -1001234567890

3. Server Name (unique identifier for this server)

   • Examples: Production, Staging, Dev, EC2-us-east-1
   • This will be used as topic prefix: [ServerName]
   • Keep it short (under 15 characters)

4. Running tmux Sessions (or installer can create them)

   • Sessions running Claude Code
   • Example: tmux new -s production -c ~/project

Usage

Starting the Bridge

With systemd (auto-restart enabled):

# Start all services
systemctl --user start [email protected]
systemctl --user start telegram-bridge.service

# Check status
systemctl --user status telegram-bridge.service

# View logs
journalctl --user -u telegram-bridge.service -f

Manual mode:

# Start bridge manually
~/.telegram-claude-bridge/bin/telegram_topic_reply_handler.py

# Or use a tmux session to keep it running
tmux new -s bridge -d ~/.telegram-claude-bridge/bin/telegram_topic_reply_handler.py

Sending Messages to Claude

1. Open your Telegram group
2. Messages in topics are automatically routed to the corresponding Claude session
3. No need to reply to specific messages - just type in the topic!

Receiving Notifications

Claude's responses are automatically sent to the appropriate Telegram topic:

• Stop hook captures Claude's output
• Messages formatted cleanly (no headers/footers)
• Long messages automatically chunked
• Topic provides all context

Managing Topics

# List current topic mappings
python3 ~/.telegram-claude-bridge/bin/telegram_topic_manager.py --list

# Create topics manually
python3 ~/.telegram-claude-bridge/bin/telegram_topic_manager.py --create

Topics are created automatically when:

• Claude sends its first notification
• A new conversation starts

Architecture

Directory Structure

~/.telegram-claude-bridge/
├── config/
│   └── telegram_bridge_config.json    # Main configuration
├── bin/                                # Executable Python modules
│   ├── telegram_topic_manager.py
│   ├── telegram_topic_reply_handler.py
│   ├── update_topic_mapping.py
│   └── utils/
│       └── telegram_helpers.py
├── hooks/                              # Claude Code hooks
│   └── telegram_notify_smart.sh
├── scripts/                            # Management scripts
│   ├── claude-session-wrapper.sh
│   └── stop-claude-session.sh
├── state/                              # Runtime state
│   ├── .telegram_topic_mappings.json
│   ├── .telegram_topic_reply_state.json
│   └── .claude_conversation_id_*
└── logs/                               # Log files
    ├── telegram_bridge.log
    └── notification_debug.log

How It Works

Sending Messages (Telegram → Claude):

1. User sends message in Telegram topic
2. telegram_topic_reply_handler.py polls for updates
3. Message routed to correct tmux session via tmux send-keys
4. Claude receives message and processes

Receiving Notifications (Claude → Telegram):

1. Claude completes processing
2. Stop hook (telegram_notify_smart.sh) triggers
3. Hook extracts conversation ID and last message
4. Topic auto-created if needed
5. Message sent to Telegram topic

Auto-Restart After Reboot:

1. Systemd starts claude-session-wrapper.sh
2. Wrapper creates tmux session with Claude
3. Detects new conversation ID
4. Updates topic mappings automatically
5. Telegram bridge reconnects

Configuration

Main Config File

~/.telegram-claude-bridge/config/telegram_bridge_config.json:

{
  "telegram": {
    "bot_token": "123456789:ABC-DEF...",
    "group_chat_id": "-1001234567890",
    "server_name": "Production"
  },
  "sessions": {
    "production": {
      "tmux_target": "production:0.0",
      "project_dir": "/home/user/project",
      "chat_id": "-1001234567890"
    }
  },
  "paths": {
    "install_dir": "/home/user/.telegram-claude-bridge",
    "state_dir": "/home/user/.telegram-claude-bridge/state",
    "log_dir": "/home/user/.telegram-claude-bridge/logs"
  }
}

Adding New Sessions

1. Edit config file to add session
2. Create systemd service (if using systemd)
3. Restart bridge

Or use the installer to reconfigure.

Testing

Unit Tests

cd telegram-claude-bridge
python3 -m unittest tests.unit.test_conversation_id_tracking -v
python3 -m unittest tests.unit.test_config_validation -v

Installation Validation

./tools/test_installation.sh

Checks:

• Directory structure
• File permissions
• Config validation
• Template substitution
• Hook installation
• Systemd services

Troubleshooting

Bridge Not Receiving Messages

1. Check bridge is running:

   systemctl --user status telegram-bridge.service
   # or
   ps aux | grep telegram_topic_reply_handler

2. Check bot has access to group:

   curl "https://api.telegram.org/bot<TOKEN>/getUpdates"

3. Check topic mappings:

   python3 ~/.telegram-claude-bridge/bin/telegram_topic_manager.py --list

Claude Not Sending Notifications

1. Check Stop hook is installed:

   cat ~/.claude/settings.json | grep telegram_notify_smart

2. Check hook has correct permissions:

   ls -l ~/.telegram-claude-bridge/hooks/telegram_notify_smart.sh

3. Check notification logs:

   tail -f ~/.telegram-claude-bridge/logs/notification_debug.log

Systemd Services Not Starting

1. Check service status:

   systemctl --user status [email protected]

2. View logs:

   journalctl --user -u [email protected] -n 50

3. Verify linger is enabled:

   loginctl show-user $USER | grep Linger

After Server Reboot

Topics should automatically update when Claude creates a new conversation ID. If not:

1. Check conversation ID files:

   ls -la ~/.telegram-claude-bridge/state/.claude_conversation_id_*

2. Manually update mapping:

   python3 ~/.telegram-claude-bridge/bin/update_topic_mapping.py \
     --session production \
     --old-conv <old-id> \
     --new-conv <new-id>

Uninstalling

cd telegram-claude-bridge
./uninstall.sh

Options to:

• Keep logs for debugging
• Remove all services
• Restore Claude settings

Multi-Server Setup

NEW in v1.1.0: Use ONE Telegram group for ALL servers!

How It Works

All servers share the same Telegram group and bot, differentiated by topic naming:

[Production] Main Feature
[Staging] Bug Fix
[Dev] Testing API

Setup Multiple Servers

Server 1 (Production):

./install.sh --non-interactive \
  --bot-token "YOUR_BOT_TOKEN" \
  --chat-id "-1001234567890" \
  --server-name "Production"

Server 2 (Staging):

./install.sh --non-interactive \
  --bot-token "YOUR_BOT_TOKEN" \    # SAME token
  --chat-id "-1001234567890" \      # SAME group
  --server-name "Staging"           # DIFFERENT name

Server 3 (Dev):

./install.sh --non-interactive \
  --bot-token "YOUR_BOT_TOKEN" \    # SAME token
  --chat-id "-1001234567890" \      # SAME group
  --server-name "Dev"               # DIFFERENT name

Topic Naming Convention

Topics are automatically created with server prefixes:

• Format: [ServerName] ConversationTitle
• Example: [Production] session - abc12345

Each server:

• Creates topics with its own [ServerName] prefix
• Only monitors and responds to topics in its own mappings
• Ignores topics from other servers

Benefits

• ✅ One group for all environments
• ✅ Easy context switching - see all servers in one place
• ✅ No authentication needed - same bot, same group
• ✅ Simple setup - no YOLO mode complexity
• ✅ Rename topics to update conversation titles
• ✅ Clean separation - server names clearly visible

Configuration Example

Shared across all servers:

{
  "telegram": {
    "bot_token": "123456789:ABC-DEF...",     // SAME
    "group_chat_id": "-1001234567890"        // SAME
  }
}

Unique per server:

{
  "telegram": {
    "server_name": "Production"              // DIFFERENT
  }
}

No YOLO Mode Needed!

The automatic group creation (YOLO mode) has been simplified. Instead:

1. Create ONE Telegram group manually
2. Add your bot to the group
3. Enable forum topics
4. Use the same group chat ID for all servers
5. Each server gets a unique server_name

Advanced Usage

Custom Session Commands

Edit telegram_bridge_config.json to add custom command handling.

Notification Customization

Edit ~/.telegram-claude-bridge/hooks/telegram_notify_smart.sh to customize:

• Message formatting
• Chunk size
• Debug logging

Multiple Claude Instances

Configure multiple sessions in install.sh or edit config manually.

Contributing

1. Fork the repository
2. Create feature branch
3. Add tests
4. Submit pull request

License

MIT License - see LICENSE file

Support

• GitHub Issues: https://github.com/yourusername/telegram-claude-bridge/issues
• Documentation: docs/

Acknowledgments

Built for seamless integration between Telegram and Claude Code CLI, enabling remote Claude access from anywhere.