Open Source Project of the Day (Part 38): Claude Code Telegram - Remote Access to Claude Code from Anywhere

A deep dive into Claude Code Telegram Bot, which gives you remote access to Claude Code via Telegram with natural-language chat, per-project session persistence, webhooks, scheduling, and a security sandbox so you can code with AI from any device

·9 min read·Tool Recommendations
Open SourceClaude CodeTelegramRemote CodingPythonBotSession Persistence

Introduction

"A Telegram bot that gives you remote access to Claude Code. Chat naturally with Claude about your projects from anywhere — no terminal commands needed."

This is Part 38 of the "Open Source Project of the Day" series. Today we look at Claude Code Telegram Bot (GitHub).

Want to keep chatting with Claude about your code from your phone or tablet without opening a laptop or SSH? Claude Code Telegram Bot connects Claude Code to Telegram: you talk in plain language and Claude reads files, edits code, and runs tests. Sessions persist per project, and you can use Agentic mode (default) or Classic mode (terminal-like commands). The bot also supports webhooks (e.g. GitHub events), scheduled jobs, and proactive notifications. Built-in whitelist, directory sandbox, rate limiting, and audit logging make it suitable for coding on the go, alone or in a small team.

Why this project?

  • 📱 Use from anywhere — Phone, tablet, or any device with Telegram
  • 💬 Natural conversation — Agentic mode by default; no commands to remember
  • 📂 Session persistence — Sessions keyed by user and project directory; pick up on another device
  • 🔔 Event-driven — Webhooks (e.g. GitHub), cron-style scheduler, and notifications to chosen chats
  • 🔒 Security — Whitelist, directory sandbox, rate limits, path checks, audit logs
  • ⚙️ Two modes — Agentic (chat) or Classic (/cd, /ls, /git, etc.)

What You'll Learn

  • What Claude Code Telegram Bot does and its two modes (Agentic vs Classic)
  • Installation and configuration (uv/pip, required .env, Telegram user ID)
  • Basic chat flow, /verbose, /repo, and GitHub workflow
  • Enabling and configuring webhooks, scheduler, and notifications
  • Security (whitelist, sandbox, rate limits, audit)
  • How it compares to local-only Claude Code or raw SSH remote access

Prerequisites

  • Claude Code CLI installed and authenticated
  • A Telegram account and a bot token from @BotFather
  • Python 3.11+ on the machine that runs the bot

Project Background

Project Introduction

Claude Code Telegram Bot is a Telegram bot that provides remote access to Claude Code. You talk to the bot in Telegram; the bot runs on your server and drives Claude Code over an approved project directory. It persists sessions per project, so you can continue the same conversation from another device or later.

Problems it solves:

  • Claude Code is mainly used in a local terminal; hard to use when away or on mobile
  • Need a lightweight, no-SSH, minimal-setup way to access it remotely
  • Want sessions to survive per project and across devices
  • Some workflows need events (e.g. auto-summarize on PR push)

Target users:

  • Developers who want to make small code changes or check status from a phone/tablet
  • Individuals or small teams sharing one “Claude Code server” with a remote entry point
  • Teams that want GitHub (or similar) events to trigger Claude for summaries or reviews
  • People who prefer Telegram and don’t want another app

Author

  • Author: RichardAtCT (GitHub)
  • Acknowledgments: Claude by Anthropic, python-telegram-bot

Project Data

  • ⭐ GitHub Stars: ~1.8k
  • 🍴 Forks: ~213
  • 📦 Version: v1.4.0 (README examples may reference v1.3.0; check Releases)
  • 📄 License: MIT
  • 📚 Docs: README, docs/setup.md, docs/configuration.md, docs/tools.md, SYSTEMD_SETUP.md

Stack: Python 3.11+, python-telegram-bot, Claude Code SDK (primary) / CLI (fallback), Poetry/uv.

Main Features

Core Purpose

The bot’s job is to expose Claude Code over Telegram, including:

  1. Natural-language chat — Ask Claude to analyze, edit, or explain code without terminal commands
  2. Session persistence — Sessions keyed by user and project directory; resume across devices and time
  3. Two modes — Agentic (default, pure chat) and Classic (/cd, /ls, /pwd, /git, etc. + inline keyboards)
  4. Event-driven — Webhooks (e.g. GitHub), cron-style scheduler, and notifications to chosen chats
  5. Security and control — User whitelist, directory sandbox, rate limits, cost caps, audit logs

Use Cases

  1. Light coding on the go — Use the bot from your phone to have Claude make a small change or run tests; results come back in Telegram.
  2. Same project, multiple devices — Start a session on your desktop, then use /repo on your phone to continue in the same project.
  3. Shared dev machine — One server runs Claude Code + bot; multiple users access via Telegram whitelist, each in their own directory.
  4. CI / GitHub integration — PRs, pushes, etc. hit the webhook; Claude summarizes or reviews; results are sent to a group or channel.
  5. Scheduled checks — Use the scheduler for daily/weekly tasks (e.g. code health, dependency suggestions) and send results via notifications.

Quick Start

Requirements: Python 3.11+, installed and authenticated Claude Code CLI, Telegram bot token from @BotFather.

Install (tagged release recommended):

# With uv (recommended, isolated)
uv tool install git+https://github.com/RichardAtCT/claude-code-telegram@v1.3.0
 
# Or with pip
pip install git+https://github.com/RichardAtCT/claude-code-telegram@v1.3.0

Configure:

cp .env.example .env
# Edit .env; minimum:
# TELEGRAM_BOT_TOKEN=...         # From @BotFather
# TELEGRAM_BOT_USERNAME=...      # Bot username
# APPROVED_DIRECTORY=...         # Allowed project root, e.g. /Users/you/projects
# ALLOWED_USERS=123456789        # Your Telegram user ID (comma-separated for multiple)

Get your Telegram user ID: Message @userinfobot on Telegram; it replies with your user ID.

Run:

make run        # Production
make run-debug  # With debug logging

Then message your bot in Telegram. For full setup and Claude auth options see docs/setup.md.

Core Features

  1. Agentic mode (default) — Natural language only; bot uses Claude Code SDK (primary) or CLI (fallback) and can show tool usage and reasoning. Commands: /start, /new, /status, /verbose, /repo; optionally /sync_threads when ENABLE_PROJECT_THREADS=true.
  2. Classic mode — Set AGENTIC_MODE=false for 13 commands: /start, /help, /new, /continue, /end, /status, /cd, /ls, /pwd, /projects, /export, /actions, /git, with inline keyboards and quick actions.
  3. Session persistence — Per user and working directory; resume later or from another device.
  4. /verbose levels — 0 (quiet), 1 (default: tool names + short reasoning), 2 (tool names + inputs + longer reasoning).
  5. /repo and GitHub — /repo lists repos in the workspace; /repo <name> switches directory and keeps session. With gh auth login on the server, you can ask Claude to run gh repo list, gh issue list, clone, create branches, push, etc.
  6. Webhook API — ENABLE_API_SERVER=true starts a FastAPI server; GitHub (HMAC-SHA256) and generic Bearer auth; events can be forwarded to Claude and results sent to Telegram.
  7. Scheduler and notifications — Cron-style jobs; notifications push agent output to NOTIFICATION_CHAT_IDS with per-chat rate limiting.
  8. Security — Whitelist (ALLOWED_USERS), directory sandbox (APPROVED_DIRECTORY, path traversal protection), rate limits, per-user cost cap (CLAUDE_MAX_COST_PER_USER), audit and security event logging.
  9. 16 configurable tools — Allowlist/disallowlist via CLAUDE_ALLOWED_TOOLS; see docs/tools.md.
  10. Project Threads — With ENABLE_PROJECT_THREADS=true, strict routing by project/topic; private or group mode; enable Threaded mode in BotFather; /sync_threads to sync topics.

Project Advantages

AspectClaude Code TelegramLocal Claude Code onlyRaw SSH + terminal
Mobile✅ Any device with Telegram❌ Need host or RDP⚠️ Need SSH client
InteractionNatural language + commandsTerminal onlyTerminal only
Persistence✅ Per projectDepends on local sessionManual
Events✅ Webhook + Cron + notifyNoneDIY
SecurityWhitelist, sandbox, auditLocal onlyDIY
SetupBot + .envCLISSH + terminal

Why choose Claude Code Telegram?

  • Same Claude Code capabilities with Telegram as the front end; good for “remote sometimes” or “same project, multiple devices.”
  • Sessions are preserved per project so you can continue from another device.
  • Extensible: webhooks, scheduler, and notifications can tie into CI, daily digests, alerts.
  • Security and control: whitelist, sandbox, cost cap, audit; suitable for self-hosted personal or small-team use.

Project Deep Dive

Architecture and Data Flow

  • User ↔ Telegram ↔ Bot (Python) ↔ Claude Code (SDK or CLI) ↔ local filesystem / Git / gh
  • Bot receives Telegram messages, parses commands or natural language, and drives Claude Code; Claude’s tool calls (Read, Edit, Bash, etc.) run on the server; the bot formats and sends results back to Telegram.
  • Session state, project directory, and history can be persisted (e.g. SQLite) for continuity and audit.

Project Structure (Summary)

  • src/ — Bot logic, Claude integration, command handling, webhook/scheduler/notification
  • config/ — Example config (e.g. projects.example.yaml for Project Threads)
  • docs/ — setup, configuration, tools
  • tests/ — Unit and integration tests
  • .env.example, Makefile — Env template and commands (run, test, lint, bump, etc.)

Configuration Highlights

  • Required: TELEGRAM_BOT_TOKEN, TELEGRAM_BOT_USERNAME, APPROVED_DIRECTORY, ALLOWED_USERS
  • Claude: ANTHROPIC_API_KEY (optional if using CLI auth); CLAUDE_MAX_COST_PER_USER, CLAUDE_TIMEOUT_SECONDS
  • Mode: AGENTIC_MODE, VERBOSE_LEVEL
  • Rate limit: RATE_LIMIT_REQUESTS, RATE_LIMIT_WINDOW
  • Events: ENABLE_API_SERVER, API_SERVER_PORT, GITHUB_WEBHOOK_SECRET, WEBHOOK_API_SECRET, ENABLE_SCHEDULER, NOTIFICATION_CHAT_IDS
  • Project Threads: ENABLE_PROJECT_THREADS, PROJECT_THREADS_MODE, PROJECTS_CONFIG_PATH, PROJECT_THREADS_CHAT_ID, etc.

Full options: docs/configuration.md and .env.example.

Troubleshooting (from README)

  • Bot not responding — Check token, ALLOWED_USERS, Claude Code installed and reachable, make run-debug for logs.
  • Claude not working — SDK: claude auth status or ANTHROPIC_API_KEY; CLI: claude --version and CLAUDE_ALLOWED_TOOLS.
  • High cost — Set CLAUDE_MAX_COST_PER_USER, use /status to monitor, keep requests focused.

Links and Resources

Official

Related

  • Claude Code — Official install and auth docs
  • Telegram Bot API — @BotFather for creating a bot and token
  • python-telegram-bot — Bot framework docs

Who It’s For

  • Developers who want to code or check status from a phone/tablet occasionally
  • Individuals or small teams who want one project, multiple devices, with persistent sessions
  • Teams that want webhooks or cron to connect GitHub/CI to Claude
  • Remote devs who prefer Telegram and want to avoid extra apps

Visit my homepage for more guides and projects.

← Back to Blog