Bridge

A Telegram bot that bridges messages to Claude Code, giving your team an AI assistant accessible via Telegram.

Setup

1. Install dependencies

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

2. Environment variables

Copy the example and fill in your values:

cp .env.example .env

Variable	Description
TELEGRAM_BOT_TOKEN	Bot token from @BotFather
ALLOWED_CHAT_IDS	Comma-separated Telegram chat IDs authorized to use the bot

3. CLAUDE.md

Create a CLAUDE.md file in the project root. This is the system prompt that defines your assistant's personality, capabilities, and instructions. It is loaded by Claude Code on every session.

touch CLAUDE.md

Write your assistant's instructions here — role, tone, team info, tool usage, response format, etc.

4. Conversations directory

The bot logs daily conversation history to conversations/ as markdown files (YYYY-MM-DD.md). Create the directory:

mkdir conversations

These logs are used for context recall across sessions.

5. Images directory

When users send images via Telegram, the bot saves them to images/. Create the directory:

mkdir images

6. MCP config (optional)

If your assistant needs MCP tools (e.g. Telegram API access), create an mcp_config.json with your MCP server definitions.

7. Run

python bot.py

Configuration

Additional settings can be configured via environment variables or in config.py:

Setting	Default	Description
CLAUDE_CLI_PATH	/opt/homebrew/bin/claude	Path to Claude Code CLI
CLAUDE_WORKING_DIR	Current directory	Working directory for Claude sessions
CLAUDE_MODEL	sonnet	Claude model to use
MAX_BUDGET_USD	1.0	Max budget per session in USD
SESSION_TTL_HOURS	24	Session timeout in hours
MCP_CONFIG_PATH	./mcp_config.json	Path to MCP server config
POLL_TIMEOUT	25	Telegram polling timeout in seconds