Skip to content

README.md

Latest commit

 

History

History
67 lines (46 loc) · 1.91 KB

README.md

File metadata and controls

67 lines (46 loc) · 1.91 KB
Raw

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