A Telegram bot that gives you Claude Code on your phone.

This is not a chatbot or personal assistant. It runs the real Claude Code CLI as a headless subprocess on your server, so you get the full agentic coding experience — file reads, edits, bash commands, multi-turn sessions — all from a Telegram chat on your phone.

Phone (Telegram)
  |
  v
Telegram Bot API
  |
  v
Bot (Python, on your VPS/server)
  |
  v
Claude Code CLI (subprocess)
  |
  v
Your project directory (reads, edits, git)

1. You send a message from Telegram on your phone
2. The bot spawns claude -p "your message" --output-format stream-json in your project directory
3. Progress updates stream back to the chat in real time ("Reading file...", "Editing file...", "Running: npm test...")
4. The result is sent back with inline action buttons

• Multi-project switching — configure multiple project directories, switch with /projects
• Session continuity — conversations resume where you left off (SQLite-backed)
• Real-time progress — see what Claude is reading, editing, or running as it works
• Git workflow buttons — Diff / Commit / Push / Undo as inline keyboard buttons
• Process cancellation — /cancel kills a long-running Claude Code process
• Concurrency locks — one request at a time per user, queued with feedback
• Large output handling — responses over 4000 chars sent as file attachments
• Auth error detection — tells you when Claude Code credentials need refreshing
• Cost tracking — shows API cost per response

This is not a general-purpose AI chatbot or personal assistant. It is a thin wrapper around the Claude Code CLI — the same tool you run in your terminal. The bot does not call the Claude API directly, does not manage its own context window, and does not implement tool use. All of that is handled by Claude Code itself.

If you want a Telegram AI assistant, look at projects like OpenClaw or Anthropic's own Claude Code Channels. This project exists for a specific use case: running Claude Code against your server's codebase from your phone.

• Python 3.11+
• Claude Code CLI installed and authenticated on the server
• Telegram bot token from @BotFather
• Your Telegram user ID from @userinfobot

# Clone
git clone https://github.com/jinsoowhang/claude-telegram-bot.git
cd claude-telegram-bot

# Configure
cp .env.example .env
# Edit .env with your token, user ID, and project paths

# Install dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Run
python bot.py

Example PROJECTS value:

{"webapp": "/home/user/my-webapp", "api": "/opt/my-api", "bot": "/opt/claude-telegram-bot"}

Create /etc/systemd/system/claude-bot.service:

[Unit]
Description=Claude Code Telegram Bot
After=network.target

[Service]
Type=simple
User=claudebot
WorkingDirectory=/opt/claude-telegram-bot
ExecStart=/opt/claude-telegram-bot/.venv/bin/python bot.py
Restart=on-failure
RestartSec=5
EnvironmentFile=/etc/claude-bot/env

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now claude-bot

After every Claude response, you get one-tap action buttons:

This bot runs with --dangerously-skip-permissions, which gives Claude Code unrestricted access to the host filesystem. See SECURITY.md for details and recommendations.

Key points:

• Only users in ALLOWED_USER_IDS can interact with the bot
• Run as a dedicated non-root user
• Do not add untrusted users to the allowlist

bot.py              Telegram handlers, commands, inline keyboards
claude_runner.py    Claude Code CLI subprocess wrapper, stream JSON parser
config.py           Environment-based configuration
sessions.py         SQLite session persistence (per-user, per-project)

The bot spawns a new claude process per request and parses its streaming JSON output. Sessions are persisted in SQLite so conversations resume across requests. Each user gets independent state (working directory, session, process lock).

MIT