Claude Code Telegram Bot 🤖

A powerful Telegram bot that provides remote access to Claude Code, enabling developers to interact with their projects from anywhere. Transform your phone into a development terminal with full Claude AI assistance, project navigation, and session persistence.

✨ What is this?

This bot bridges Telegram and Claude Code, allowing you to:

💬 Chat with Claude about your code projects through Telegram
📁 Navigate directories and manage files remotely
🔄 Maintain context across conversations with session persistence
📱 Code on the go from any device with Telegram
🛡️ Stay secure with built-in authentication and sandboxing

Perfect for code reviews on mobile, quick fixes while traveling, or getting AI assistance when away from your development machine.

🚀 Quick Start

Demo

You: cd my-project
Bot: 📂 Changed to: my-project/

You: ls  
Bot: 📁 src/
     📁 tests/
     📄 README.md
     📄 package.json

You: Can you help me add error handling to src/api.py?
Bot: 🤖 I'll help you add robust error handling to your API...
     [Claude analyzes your code and suggests improvements]

✨ Features

🚧 Development Status

This project is actively being developed. Here's the current status of features:

✅ Working Features

Full Telegram bot functionality with advanced command handling
Directory navigation (cd, ls, pwd) with project switching
Multi-layer authentication (whitelist + optional token-based)
Advanced rate limiting with token bucket algorithm
Complete Claude integration with SDK/CLI support
✨ Enhanced file upload handling with archive extraction
✨ Git integration with safe repository operations
✨ AI-generated suggestion buttons (replaces static quick actions)
✨ Session export in Markdown, HTML, and JSON formats
✨ Image/screenshot upload with smart analysis prompts
✨ Clickable suggestions that execute as new prompts
SQLite database persistence with migrations
Comprehensive usage and cost tracking
Session management with persistence
✨ User session persistence across bot restarts (PicklePersistence)
Audit logging and security event tracking

🚀 New Advanced Features

📦 Archive Analysis: Upload ZIP/TAR files for comprehensive project analysis
🔄 Git Operations: View status, diffs, logs, and commit history
💡 AI Suggestions: Claude generates contextual next-step buttons from responses
📤 Session Export: Download conversation history in multiple formats
🖼️ Image Support: Upload screenshots and diagrams for analysis
🔘 Clickable Actions: Suggestion buttons execute as new prompts when clicked

🔄 Planned Enhancements

True streaming responses with real-time updates
Claude vision API integration for full image analysis
Suggestion persistence across sessions
Advanced Git operations (when security permits)
Plugin system for third-party extensions
Multi-language code execution
Webhook support for CI/CD integration

🤖 Claude AI Integration

Full Claude Code Access: Complete integration with Claude's powerful coding assistant
Session Persistence: Maintain conversation context with SQLite database storage
SDK & CLI Support: Works with both Anthropic Python SDK and Claude CLI
Error Recovery: Intelligent error handling with helpful suggestions and retry logic
Tool Support: Access to Claude's full toolkit including file operations, code analysis, and more

📱 Terminal-like Interface

Directory Navigation: cd, ls, pwd commands just like a real terminal
File Management: Upload files, archives, and images for Claude to analyze
Git Integration: View repository status, diffs, and commit history
Project Switching: Easy navigation between different codebases with context preservation
Command History: Full session tracking with export capabilities

🛡️ Enterprise-Grade Security

Multi-Layer Authentication: Whitelist-based and optional token authentication
Directory Isolation: Strict sandboxing to approved project directories
Rate Limiting: Token bucket algorithm with request and cost-based limits
Comprehensive Audit Logging: Complete tracking of all user actions and security events
Input Validation: Protection against injection attacks, path traversal, and zip bombs

⚡ Developer Experience

AI Suggestions: Claude generates clickable next-step buttons based on response content
Session Management: Start, continue, end, export, and monitor Claude sessions
Usage Analytics: Detailed cost tracking, usage patterns, and system statistics
Responsive Design: Clean, mobile-friendly interface with inline keyboards
One-Click Actions: Suggestion buttons execute as new prompts when clicked

🛠️ Installation

Prerequisites

Python 3.9+ - Download here
Poetry - Modern Python dependency management
Claude Code CLI - Install from here
Telegram Bot Token - Get one from @BotFather

1. Get Your Bot Token

Message @BotFather on Telegram
Send /newbot and follow the prompts
Save your bot token (it looks like 1234567890:ABC...)
Note your bot username (e.g., my_claude_bot)

2. Set Up Claude Authentication

Choose one of these authentication methods:

Option 1: Use existing Claude CLI login (Recommended)

# Install Claude CLI
# Follow instructions at https://claude.ai/code

# Authenticate with Claude
claude

# follow the prompts to authenticate

# The bot will automatically use your CLI credentials

Option 2: Use API key directly

# Get your API key from https://console.anthropic.com/
# You'll add this to your .env file in the next step

3. Install the Bot

# Clone the repository
git clone https://github.com/yourusername/claude-code-telegram.git
cd claude-code-telegram

# Install Poetry (if needed)
curl -sSL https://install.python-poetry.org | python3 -

# Install dependencies
make dev

4. Configure Environment

# Copy the example configuration
cp .env.example .env

# Edit with your settings
nano .env

Minimum required configuration:

TELEGRAM_BOT_TOKEN=1234567890:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TELEGRAM_BOT_USERNAME=my_claude_bot
APPROVED_DIRECTORY=/Users/yourname/projects
ALLOWED_USERS=123456789  # Your Telegram user ID

5. Run the Bot

# Start in debug mode
make run-debug

# Or for production
make run

🎉 That's it! Message your bot on Telegram to get started.

📋 Detailed Setup Guide: For comprehensive setup instructions including authentication options and troubleshooting, see docs/setup.md

📱 Usage

Basic Commands

Once your bot is running, you can use these commands in Telegram:

Navigation Commands

/ls                    # List files in current directory
/cd myproject         # Change to project directory  
/pwd                  # Show current directory
/projects             # Show available projects

Session Management

/new                  # Start a new Claude session
/continue [message]   # Continue previous session (optionally with message)
/end                  # End current session
/status               # Show session status and usage
/export               # Export session (choose format: Markdown, HTML, JSON)

Advanced Features

/git                  # Show git repository info (status, diff, log)
/actions              # Show context-aware quick actions

Getting Help

/start                # Welcome message and setup
/help                 # Show all available commands

Talking to Claude

Just send any message to interact with Claude about your code:

You: "Analyze this Python function for potential bugs"
You: "Help me optimize this database query"  
You: "Create a React component for user authentication"
You: "Explain what this code does"

File Operations

Upload files: Simply send files to Telegram and Claude will analyze them.

Supported operations:

Single files: Code files, configs, documents - Claude analyzes content
Archives: ZIP/TAR files - Extracts and analyzes project structure
Images: Screenshots, diagrams, UI mockups - Smart prompt generation
Multiple files: Send several files for batch analysis

Supported file types: .py, .js, .ts, .jsx, .tsx, .java, .cpp, .c, .go, .rs, .rb, .php, .swift, .kt, .scala, .sql, .json, .xml, .html, .css, .md, .txt, .yaml, .toml, .zip, .tar, .tar.gz, .png, .jpg, .jpeg, .gif, .webp, and more.

Example Workflow

1. You: /cd my-web-app
   Bot: 📂 Changed to: my-web-app/

2. You: /ls
   Bot: 📁 src/
        📁 components/  
        📄 package.json
        📄 README.md

3. You: "Can you help me add TypeScript to this project?"
   Bot: 🤖 I'll help you migrate to TypeScript! Let me analyze your project structure...
        [Claude provides detailed migration steps]

4. You: /status
   Bot: 📊 Session Status
        📂 Directory: my-web-app/
        🤖 Claude Session: ✅ Active  
        💰 Usage: $0.15 / $10.00 (2%)

Advanced Features Examples

📦 Archive Analysis

You: [Upload project.zip]
Bot: 📦 Analyzing archive: project.zip
     
     Project Structure:
     📁 src/
       📄 main.py (2.3KB)
       📄 utils.py (1.1KB)
     📁 tests/
       📄 test_main.py (3.2KB)
     📄 requirements.txt (245B)
     
     Language: Python
     Frameworks: pytest detected
     Entry point: src/main.py
     
     🤖 I've analyzed your Python project. It appears to be...

🔄 Git Integration

You: /git
Bot: 📊 Git Repository Status
     
     🌿 Branch: feature/new-api
     📝 Changes: 3 files modified
     🔄 Behind main: 2 commits
     
     Recent commits:
     • abc123 - Add API endpoint (2 hours ago)
     • def456 - Update dependencies (1 day ago)
     
     [View Diff] [Show Log] [See Changes]

⚡ Quick Actions

You: /actions
Bot: 🚀 Available Quick Actions
     
     Based on your project context:
     [🧪 Run Tests] [📦 Install Deps]
     [🎨 Format Code] [🔍 Run Linter]
     [📝 Add Docs] [🔧 Refactor]

📤 Session Export

You: /export
Bot: 📤 Export Session
     
     Choose format:
     [📝 Markdown] [🌐 HTML] [📋 JSON]
     
You: [Click Markdown]
Bot: ✅ Session exported!
     📎 claude_session_abc123.md (15.2KB)
     [Downloads as file in Telegram]

AI-Generated Suggestions

The bot supports AI-generated suggestion buttons that appear after Claude's responses. When Claude outputs suggestions in a special format, they're rendered as clickable buttons.

How it works:

Claude responds with helpful next steps in [SUGGESTIONS]...[/SUGGESTIONS] format
The bot parses these and displays them as inline keyboard buttons
Clicking a button sends that suggestion as your next message to Claude

Example Claude output:

I've fixed the authentication bug in src/auth.py.

[SUGGESTIONS]
1. Run the tests to verify the fix
2. Review the changes I made
3. Deploy to staging
[/SUGGESTIONS]

What you see:

I've fixed the authentication bug in src/auth.py.

[💡 Run the tests to verify...]
[💡 Review the changes I ma...]
[💡 Deploy to staging]

To enable suggestions: Add this instruction to your Claude system prompt:

When responding via Telegram, if helpful next steps exist, append:
[SUGGESTIONS]
1. First suggestion
2. Second suggestion
3. Third suggestion (optional)
[/SUGGESTIONS]
Only include when genuinely useful. Max 3 suggestions.

⚙️ Configuration

Required Settings

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=1234567890:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TELEGRAM_BOT_USERNAME=my_claude_bot

# Security - Base directory for project access (absolute path)
APPROVED_DIRECTORY=/Users/yourname/projects

# User Access Control
ALLOWED_USERS=123456789,987654321  # Your Telegram user ID(s)

Common Optional Settings

# Claude Settings
USE_SDK=true                        # Use Python SDK (default) or CLI subprocess
ANTHROPIC_API_KEY=sk-ant-api03-...  # Optional: API key for SDK (if not using CLI auth)
CLAUDE_MAX_COST_PER_USER=10.0       # Max cost per user in USD
CLAUDE_TIMEOUT_SECONDS=300          # Timeout for operations  
CLAUDE_ALLOWED_TOOLS="Read,Write,Edit,Bash,Glob,Grep,LS,Task,MultiEdit,NotebookRead,NotebookEdit,WebFetch,TodoRead,TodoWrite,WebSearch"

# Rate Limiting  
RATE_LIMIT_REQUESTS=10              # Requests per window
RATE_LIMIT_WINDOW=60                # Window in seconds

# Features
ENABLE_GIT_INTEGRATION=true
ENABLE_FILE_UPLOADS=true
ENABLE_QUICK_ACTIONS=true

# Development
DEBUG=false
LOG_LEVEL=INFO

📋 Full configuration reference: See .env.example for all available options with detailed descriptions.

Finding Your Telegram User ID

To get your Telegram user ID for the ALLOWED_USERS setting:

Message @userinfobot on Telegram
It will reply with your user ID number
Add this number to your ALLOWED_USERS setting

🔧 Troubleshooting

Common Issues

Bot doesn't respond:

✅ Check your TELEGRAM_BOT_TOKEN is correct
✅ Verify your user ID is in ALLOWED_USERS
✅ Ensure Claude Code CLI is installed and accessible
✅ Check bot logs for error messages

"Permission denied" errors:

✅ Verify APPROVED_DIRECTORY path exists and is readable
✅ Ensure the bot process has file system permissions
✅ Check that paths don't contain special characters

Claude integration not working:

If using SDK mode (USE_SDK=true, which is default):

✅ Check CLI authentication: claude auth status
✅ If no CLI auth, verify ANTHROPIC_API_KEY is set in .env
✅ Ensure API key has sufficient credits
✅ Check logs for "SDK initialization" messages

If using CLI mode (USE_SDK=false):

✅ Verify Claude CLI is installed: claude --version
✅ Check CLI authentication: claude auth status
✅ Ensure CLI has sufficient credits

General troubleshooting:

✅ Verify CLAUDE_ALLOWED_TOOLS includes necessary tools
✅ Check CLAUDE_TIMEOUT_SECONDS isn't too low
✅ Monitor usage with /status command

High usage costs:

✅ Adjust CLAUDE_MAX_COST_PER_USER to set spending limits
✅ Monitor usage with /status command
✅ Use shorter, more focused requests
✅ End sessions when done with /end

Getting Help

📖 Documentation: Check this README and .env.example
🐛 Bug Reports: Open an issue
💬 Discussions: GitHub Discussions
🔒 Security: See SECURITY.md for reporting security issues

🛡️ Security

This bot implements enterprise-grade security:

🔐 Access Control: Whitelist-based user authentication
📁 Directory Isolation: Strict sandboxing to approved directories
⏱️ Rate Limiting: Request and cost-based limits prevent abuse
🛡️ Input Validation: Protection against injection attacks
📊 Audit Logging: Complete tracking of all user actions
🔒 Secure Defaults: Principle of least privilege throughout

PAI Security Integration

When running within the PAI (Personal AI Infrastructure) system, this bot operates with a two-layer security architecture:

Layer	Location	Purpose
PAI Security Hook	`~/.claude/hooks/SecurityValidator.hook.ts`	Nuanced pattern detection (e.g., allows `curl \| jq` but blocks `curl \| sh`)
Bot Monitor	`src/claude/monitor.py`	Catastrophic operation blocking (e.g., `rm -rf /`, disk formatting)

Coordination principle: PAI handles nuanced, context-aware security patterns. The bot monitor only blocks operations that are NEVER safe, regardless of context.

When modifying security:

Check both ~/.claude/skills/PAI/USER/PAISECURITYSYSTEM/patterns.yaml (PAI) and src/claude/monitor.py (bot)
Avoid duplicating patterns — this causes false positives
Test with real Telegram commands after changes

For security issues, see SECURITY.md.

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Setup

# Fork and clone the repository
git clone https://github.com/yourusername/claude-code-telegram.git
cd claude-code-telegram

# Install development dependencies
make dev

# Run tests to verify setup
make test

Development Commands

make help          # Show all available commands
make test          # Run tests with coverage  
make lint          # Run code quality checks
make format        # Auto-format code
make run-debug     # Run bot in debug mode

Contribution Guidelines

🍴 Fork the repository
🌿 Create a feature branch: git checkout -b feature/amazing-feature
✨ Make your changes with tests
✅ Test your changes: make test && make lint
📝 Commit your changes: git commit -m 'Add amazing feature'
🚀 Push to the branch: git push origin feature/amazing-feature
🎯 Submit a Pull Request

Code Standards

Python 3.9+ with type hints
Black formatting (88 char line length)
pytest for testing with >85% coverage
mypy for static type checking
Conventional commits for commit messages

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 Star History

If you find this project useful, please consider giving it a star! ⭐

🙏 Acknowledgments

Claude by Anthropic for the amazing AI capabilities
python-telegram-bot for the excellent Telegram integration
All contributors who help make this project better

Made with ❤️ for developers who code on the go

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
docs		docs
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
FEATURE_IMPLEMENTATION_SUMMARY.md		FEATURE_IMPLEMENTATION_SUMMARY.md
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml
setup.cfg		setup.cfg

Folders and files

Latest commit

History

Repository files navigation

Claude Code Telegram Bot 🤖

✨ What is this?

🚀 Quick Start

Demo

✨ Features

🚧 Development Status

✅ Working Features

🚀 New Advanced Features

🔄 Planned Enhancements

🤖 Claude AI Integration

📱 Terminal-like Interface

🛡️ Enterprise-Grade Security

⚡ Developer Experience

🛠️ Installation

Prerequisites

1. Get Your Bot Token

2. Set Up Claude Authentication

3. Install the Bot

4. Configure Environment

5. Run the Bot

📱 Usage

Basic Commands

Navigation Commands

Session Management

Advanced Features

Getting Help

Talking to Claude

File Operations

Example Workflow

Advanced Features Examples

📦 Archive Analysis

🔄 Git Integration

⚡ Quick Actions

📤 Session Export

AI-Generated Suggestions

⚙️ Configuration

Required Settings

Common Optional Settings

Finding Your Telegram User ID

🔧 Troubleshooting

Common Issues

Getting Help

🛡️ Security

PAI Security Integration

🤝 Contributing

Development Setup

Development Commands

Contribution Guidelines

Code Standards

📄 License

🌟 Star History

🙏 Acknowledgments

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages