Claude Code Telegram Bot

English | Русский

Control Claude Code CLI through Telegram. Execute commands, analyze files, and manage your server directly from your phone.

✨ Features

• Full Claude Code Access — Execute any Claude Code command via Telegram
• Session Persistence — Context preserved between messages (stored in PostgreSQL)
• File Support — Upload and analyze files and images
• Safe by Default — Read-only mode unless you explicitly request changes
• Command Cancellation — Cancel long-running operations with
  /cancel
• Timeout Protection — 5-minute timeout prevents hanging processes
• Access Control — Restrict bot access to specific Telegram user IDs
• Graceful Shutdown — Clean termination of all processes

📋 Prerequisites

• Python 3.9+
• PostgreSQL 12+
• Claude Code CLI installed (
  npm install -g @anthropic-ai/claude-code
  )
• Telegram Bot Token (from @BotFather)

🚀 Quick Start

1. Clone the repository

2. Create virtual environment

3. Install dependencies

4. Configure environment

5. Create database

6. Run the bot

🐳 Docker Installation

⚙️ Configuration

Getting Your Telegram User ID

Send

📖 Usage

Bot Commands

Execution Keywords

Commands are executed only when you use trigger keywords:

Russian:

English:

Examples

Information only (no execution):

Show me the list of files
What does this script do?
Check nginx status

With execution:

Restart nginx service
Create a new Python script
Fix the error in bot.py

File Uploads

Upload any file to the chat and Claude will analyze it:

• Images — Visual analysis and description
• Code files — Code review and suggestions
• Logs — Error analysis and troubleshooting
• Documents — Content extraction and summary

🏗️ Architecture

claude-code-bot/
├── bot/
│   ├── __init__.py
│   ├── main.py              # Entry point, application setup
│   ├── config.py            # Configuration from environment
│   ├── handlers/
│   │   ├── __init__.py
│   │   ├── commands.py      # Bot command handlers
│   │   ├── messages.py      # Text message handler
│   │   └── files.py         # File upload handler
│   ├── services/
│   │   ├── __init__.py
│   │   ├── claude.py        # Claude CLI executor
│   │   ├── session.py       # Session management
│   │   └── formatter.py     # Telegram HTML formatter
│   └── database/
│       ├── __init__.py
│       └── pool.py          # PostgreSQL connection pool
├── user_files/              # Uploaded files storage
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── LICENSE
└── README.md

🔐 Security

Access Control

• Set
  ALLOWED_USER_ID
  to restrict access to specific Telegram user IDs
• Multiple IDs can be comma-separated:
  123456789,987654321
• Warning: Without this setting, anyone can use your bot!

Safe Execution

• Commands run in read-only mode by default
• Explicit trigger keywords required for modifications
• Safety instructions embedded in every prompt

Timeout Protection

• 5-minute timeout on all Claude operations
• Cancel any time with
  /cancel

🖥️ Systemd Service

Create

Enable and start:

View logs:

🔧 Troubleshooting

Bot not responding

1. Check logs:
   journalctl -u claude-code-bot -f
2. Verify Claude CLI works:
   claude --version
3. Check database connection:
   psql -h localhost -U your_user -d claude_code_bot

Timeout errors

1. Increase
   CLAUDE_TIMEOUT
   in
   .env
2. Simplify your request
3. Check if Claude CLI is responding:
   claude "Hello"

Permission errors

1. Ensure bot runs as user with Claude CLI access
2. Check working directory permissions
3. Verify file upload directory is writable

Database errors

1. Check PostgreSQL is running:
   systemctl status postgresql
2. Verify credentials in
   .env
3. Check database exists:
   psql -l | grep claude_code_bot

📝 Database Schema

The bot uses two tables:

sessions — User session data

command_logs — Command history

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch:
   git checkout -b feature/amazing-feature
3. Commit your changes:
   git commit -m 'Add amazing feature'
4. Push to the branch:
   git push origin feature/amazing-feature
5. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• Anthropic for Claude and Claude Code
• python-telegram-bot for the excellent Telegram library

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions