Claude Code Telegram Bot#

Overview#

Claude Code Telegram Bot serves as middleware connecting Telegram with Anthropic's Claude Code capabilities. Its core objective is to break the boundary of using Claude Code only in local terminals or IDEs, allowing developers to control Claude Code for code writing, refactoring, debugging, and file operations through mobile or remote desktop via natural language conversations.

This project not only provides a basic chat gateway but also includes complete session lifecycle management (automatic persistence and recovery), enterprise-grade security controls (user whitelist, directory sandbox, rate limiting), and an extensible event-driven architecture. Beyond manual interactions, users can trigger Claude to execute automated tasks via GitHub Webhooks or the built-in Job Scheduler, with results pushed to designated Telegram groups or channels.

Core Features#

Interaction Modes#

• Agentic Mode (Default): Natural language driven, no need to memorize complex commands, Claude automatically parses intent and executes. Supports 5 core commands: /start, /new, /status, /verbose, /repo.
• Classic Mode: Traditional CLI style, provides 13 terminal-like commands including /cd, /ls, /pwd, /projects, suitable for users accustomed to command lines.
• Multi-verbosity: Control output verbosity via /verbose 0|1|2 (quiet/normal/detailed) to adapt to different information needs.

Session & Storage#

• Session Persistence: Automatic session persistence based on user ID and project directory, supports resumption from breakpoints without repeating context.
• Project Threads: Supports multi-project switching and management, each project maintains independent session context.
• Media Support: Supports uploading images and files to Claude for multimodal analysis.

Automation & Events#

• Webhook API Server: Built-in FastAPI service supporting GitHub (HMAC-SHA256) and Generic (Bearer Token) authentication methods for external event triggering.
• Job Scheduler: Cron-based task scheduling via APScheduler, supports timed triggers for Claude tasks (e.g., daily code checks).
• Notification Service: Supports sharded push and broadcast with built-in rate limiting to prevent message flooding.

Security & Control#

• Access Control: Whitelist mechanism based on Telegram User ID, unauthorized users cannot interact.
• Sandbox Isolation: Directory sandbox isolation, limiting Claude to only access approved directories.
• Cost Control: Supports CLAUDE_MAX_COST_PER_USER configuration to set spending limits per user (USD).
• Rate Limiting: Request frequency limiting to prevent abuse.
• Audit Logging: Records operation logs for auditing and tracing.

Claude Integration#

• Dual Backend: Supports SDK (recommended) and CLI (fallback) modes for Claude interaction.
• Tool Management: Supports Allowlist/Disallowlist configuration for 16 built-in tools for fine-grained control of Claude capabilities.
• Cost Tracking: Real-time tracking of API call costs.

Architecture#

Core Components#

• MessageOrchestrator (src/bot/orchestrator.py): Core routing layer, distributes Telegram messages to Agentic or Classic handlers.
• Claude Integration (src/claude/): Facade pattern encapsulating SDK and CLI backend implementations with unified interface.
• Storage Layer (src/storage/): SQLite-based data persistence layer using Repository pattern, managing session state, scheduled tasks, etc.
• Security (src/security/): Handles user authentication, permission verification, and token management.
• Event Bus (src/events/): Async Pub/Sub system decoupling Webhook/Scheduler triggers from Claude execution logic.
• API Server (src/api/): FastAPI-based webhook receiving service.

Data Flow#

Direct Interaction Flow:

User Message → Telegram API → Middleware (Auth/RateLimit) 
    → MessageOrchestrator → ClaudeIntegration → Claude API/CLI 
    → Response → Telegram

Event-Driven Flow:

External Event (GitHub/Cron) → Webhook/API Server → EventBus 
    → AgentHandler → ClaudeIntegration → AgentResponseEvent 
    → NotificationService → Telegram

Quick Start#

Prerequisites#

• Python 3.11 or higher
• Claude Code CLI (installed and configured)
• Telegram Bot Token (obtained from @BotFather)

Installation#

Recommended (from Release):

# Using uv
uv tool install git+https://github.com/RichardAtCT/claude-code-telegram@v1.3.0

# Using pip
pip install git+https://github.com/RichardAtCT/claude-code-telegram@v1.3.0

From Source:

git clone https://github.com/RichardAtCT/claude-code-telegram.git
cd claude-code-telegram
make dev  # Requires Poetry for environment setup

Configuration#

Copy .env.example to .env and fill in key configurations:

# Basic Configuration
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_BOT_USERNAME=your_bot_username
APPROVED_DIRECTORY=/path/to/your/projects
ALLOWED_USERS=123456789,987654321

# Claude Configuration (SDK mode recommended)
USE_SDK=true
ANTHROPIC_API_KEY=sk-ant-...
CLAUDE_MAX_COST_PER_USER=10.0
CLAUDE_TIMEOUT_SECONDS=300
CLAUDE_ALLOWED_TOOLS=Read,Write,Edit,Bash

# Mode Configuration
AGENTIC_MODE=true
VERBOSE_LEVEL=1

# Event-Driven Platform (optional)
ENABLE_API_SERVER=false
ENABLE_SCHEDULER=false

Run#

make run          # Production mode
make run-debug    # Debug mode (verbose logging)

Use Cases#

1. Mobile Development: Use Claude Code on any device via Telegram
2. Team Sharing: Multiple users sharing Claude Code access
3. Automated Tasks: Trigger Claude tasks via webhook/scheduler
4. Remote Project Management: Manage multiple projects with automatic session recovery

Example Interaction#

User: Can you help me add error handling to src/api.py?
Bot: I'll analyze src/api.py and add error handling...
     [Claude reads code, suggests improvements, applies changes]

User: Run the tests to make sure nothing broke.
Bot: Running pytest...
     All 47 tests passed. The error handling changes are working correctly.

Version Info#

• Current Version: v1.3.0
• Primary Language: Python (99.6%)
• License: MIT License