Claude Code Telegram Bridge

Send messages from Telegram to Claude Code CLI and get streamed responses back. Runs on your existing Claude Max subscription -- no API key needed.

Features

• Real-time streaming responses (edits the Telegram message as Claude types)
• Image support (photos sent in Telegram are passed to Claude as base64)
• Document uploads (files are saved to workspace and referenced in the prompt)
• Conversation history (rolling 20-message context window)
• Markdown-to-HTML conversion for Telegram formatting
• Single-user security (only responds to your Telegram ID)
• Systemd service installer for always-on operation

Setup

1. Create a Telegram Bot

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

2. Get Your Telegram User ID

Send a message to @userinfobot to get your numeric user ID.

3. Install

git clone https://github.com/jonathancaruso/claude-telegram.git
cd claude-telegram
npm install
cp .env.example .env
# Edit .env with your bot token, user ID, workspace path, and claude path

4. Run

# Direct
node bot.js

# Or install as a systemd user service (Linux)
export BOT_TOKEN=your-token
export ALLOWED_USER=your-user-id
export WORKSPACE=/path/to/workspace
./install.sh

Commands

• /start -- Show help
• /stop or /cancel -- Kill the running Claude process
• /status -- Check if Claude is working on something
• /clear -- Clear conversation history

How It Works

Each message spawns a fresh claude --print process with your prompt. A rolling history file injects the last 20 exchanges as context so Claude has conversational continuity. Responses stream back via Telegram message edits every 2 seconds.

Requirements

• Node.js 18+
• Claude Code CLI installed and authenticated
• A Telegram bot token

License

MIT