[](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) A Telegram bot that gives you remote access to Claude Code. Chat naturally with Claude about your projects from anywhere -- no terminal commands needed. What is this? This bot connects Telegram to Claude Code, providing a conversational AI interface for your codebase: - Chat naturally -- ask Claude to analyze, edit, or e
Add this skill
npx mdskills install RichardAtCT/claude-code-telegramWell-documented Telegram bot connecting Claude Code for remote codebase access with strong security features
1# Claude Code Telegram Bot23[](https://opensource.org/licenses/MIT)4[](https://www.python.org/downloads/)56A Telegram bot that gives you remote access to [Claude Code](https://claude.ai/code). Chat naturally with Claude about your projects from anywhere -- no terminal commands needed.78## What is this?910This bot connects Telegram to Claude Code, providing a conversational AI interface for your codebase:1112- **Chat naturally** -- ask Claude to analyze, edit, or explain your code in plain language13- **Maintain context** across conversations with automatic session persistence per project14- **Code on the go** from any device with Telegram15- **Receive proactive notifications** from webhooks, scheduled jobs, and CI/CD events16- **Stay secure** with built-in authentication, directory sandboxing, and audit logging1718## Quick Start1920### Demo2122```23You: Can you help me add error handling to src/api.py?2425Bot: I'll analyze src/api.py and add error handling...26 [Claude reads your code, suggests improvements, and can apply changes directly]2728You: Looks good. Now run the tests to make sure nothing broke.2930Bot: Running pytest...31 All 47 tests passed. The error handling changes are working correctly.32```3334### 1. Prerequisites3536- **Python 3.10+** -- [Download here](https://www.python.org/downloads/)37- **Poetry** -- Modern Python dependency management38- **Claude Code CLI** -- [Install from here](https://claude.ai/code)39- **Telegram Bot Token** -- Get one from [@BotFather](https://t.me/botfather)4041### 2. Install4243```bash44git clone https://github.com/RichardAtCT/claude-code-telegram.git45cd claude-code-telegram46make dev47```4849### 3. Configure5051```bash52cp .env.example .env53# Edit .env with your settings:54```5556**Minimum required:**57```bash58TELEGRAM_BOT_TOKEN=1234567890:ABC-DEF1234ghIkl-zyx57W2v1u123ew1159TELEGRAM_BOT_USERNAME=my_claude_bot60APPROVED_DIRECTORY=/Users/yourname/projects61ALLOWED_USERS=123456789 # Your Telegram user ID62```6364### 4. Run6566```bash67make run # Production68make run-debug # With debug logging69```7071Message your bot on Telegram to get started.7273> **Detailed setup:** See [docs/setup.md](docs/setup.md) for Claude authentication options and troubleshooting.7475## Modes7677The bot supports two interaction modes:7879### Agentic Mode (Default)8081The default conversational mode. Just talk to Claude naturally -- no special commands required.8283**Commands:** `/start`, `/new`, `/status`, `/verbose`, `/repo`84If `ENABLE_PROJECT_THREADS=true`: `/sync_threads`8586```87You: What files are in this project?88Bot: Working... (3s)89 📖 Read90 📂 LS91 💬 Let me describe the project structure92Bot: [Claude describes the project structure]9394You: Add a retry decorator to the HTTP client95Bot: Working... (8s)96 📖 Read: http_client.py97 💬 I'll add a retry decorator with exponential backoff98 ✏️ Edit: http_client.py99 💻 Bash: poetry run pytest tests/ -v100Bot: [Claude shows the changes and test results]101102You: /verbose 0103Bot: Verbosity set to 0 (quiet)104```105106Use `/verbose 0|1|2` to control how much background activity is shown:107108| Level | Shows |109|-------|-------|110| **0** (quiet) | Final response only (typing indicator stays active) |111| **1** (normal, default) | Tool names + reasoning snippets in real-time |112| **2** (detailed) | Tool names with inputs + longer reasoning text |113114#### GitHub Workflow115116Claude Code already knows how to use `gh` CLI and `git`. Authenticate on your server with `gh auth login`, then work with repos conversationally:117118```119You: List my repos related to monitoring120Bot: [Claude runs gh repo list, shows results]121122You: Clone the uptime one123Bot: [Claude runs gh repo clone, clones into workspace]124125You: /repo126Bot: 📦 uptime-monitor/ ◀127 📁 other-project/128129You: Show me the open issues130Bot: [Claude runs gh issue list]131132You: Create a fix branch and push it133Bot: [Claude creates branch, commits, pushes]134```135136Use `/repo` to list cloned repos in your workspace, or `/repo <name>` to switch directories (sessions auto-resume).137138### Classic Mode139140Set `AGENTIC_MODE=false` to enable the full 13-command terminal-like interface with directory navigation, inline keyboards, quick actions, git integration, and session export.141142**Commands:** `/start`, `/help`, `/new`, `/continue`, `/end`, `/status`, `/cd`, `/ls`, `/pwd`, `/projects`, `/export`, `/actions`, `/git`143If `ENABLE_PROJECT_THREADS=true`: `/sync_threads`144145```146You: /cd my-web-app147Bot: Directory changed to my-web-app/148149You: /ls150Bot: src/ tests/ package.json README.md151152You: /actions153Bot: [Run Tests] [Install Deps] [Format Code] [Run Linter]154```155156## Event-Driven Automation157158Beyond direct chat, the bot can respond to external triggers:159160- **Webhooks** -- Receive GitHub events (push, PR, issues) and route them through Claude for automated summaries or code review161- **Scheduler** -- Run recurring Claude tasks on a cron schedule (e.g., daily code health checks)162- **Notifications** -- Deliver agent responses to configured Telegram chats163164Enable with `ENABLE_API_SERVER=true` and `ENABLE_SCHEDULER=true`. See [docs/setup.md](docs/setup.md) for configuration.165166## Features167168### Working Features169170- Conversational agentic mode (default) with natural language interaction171- Classic terminal-like mode with 13 commands and inline keyboards172- Full Claude Code integration with SDK (primary) and CLI (fallback)173- Automatic session persistence per user/project directory174- Multi-layer authentication (whitelist + optional token-based)175- Rate limiting with token bucket algorithm176- Directory sandboxing with path traversal prevention177- File upload handling with archive extraction178- Image/screenshot upload with analysis179- Git integration with safe repository operations180- Quick actions system with context-aware buttons181- Session export in Markdown, HTML, and JSON formats182- SQLite persistence with migrations183- Usage and cost tracking184- Audit logging and security event tracking185- Event bus for decoupled message routing186- Webhook API server (GitHub HMAC-SHA256, generic Bearer token auth)187- Job scheduler with cron expressions and persistent storage188- Notification service with per-chat rate limiting189190- Tunable verbose output showing Claude's tool usage and reasoning in real-time191- Persistent typing indicator so users always know the bot is working192193### Planned Enhancements194195- Plugin system for third-party extensions196197## Configuration198199### Required200201```bash202TELEGRAM_BOT_TOKEN=... # From @BotFather203TELEGRAM_BOT_USERNAME=... # Your bot's username204APPROVED_DIRECTORY=... # Base directory for project access205ALLOWED_USERS=123456789 # Comma-separated Telegram user IDs206```207208### Common Options209210```bash211# Claude212ANTHROPIC_API_KEY=sk-ant-... # API key (optional if using CLI auth)213CLAUDE_MAX_COST_PER_USER=10.0 # Spending limit per user (USD)214CLAUDE_TIMEOUT_SECONDS=300 # Operation timeout215216# Mode217AGENTIC_MODE=true # Agentic (default) or classic mode218VERBOSE_LEVEL=1 # 0=quiet, 1=normal (default), 2=detailed219220# Rate Limiting221RATE_LIMIT_REQUESTS=10 # Requests per window222RATE_LIMIT_WINDOW=60 # Window in seconds223224# Features (classic mode)225ENABLE_GIT_INTEGRATION=true226ENABLE_FILE_UPLOADS=true227ENABLE_QUICK_ACTIONS=true228```229230### Agentic Platform231232```bash233# Webhook API Server234ENABLE_API_SERVER=false # Enable FastAPI webhook server235API_SERVER_PORT=8080 # Server port236237# Webhook Authentication238GITHUB_WEBHOOK_SECRET=... # GitHub HMAC-SHA256 secret239WEBHOOK_API_SECRET=... # Bearer token for generic providers240241# Scheduler242ENABLE_SCHEDULER=false # Enable cron job scheduler243244# Notifications245NOTIFICATION_CHAT_IDS=123,456 # Default chat IDs for proactive notifications246```247248### Project Threads Mode249250```bash251# Enable strict topic routing by project252ENABLE_PROJECT_THREADS=true253254# Mode: private (default) or group255PROJECT_THREADS_MODE=private256257# YAML registry file (see config/projects.example.yaml)258PROJECTS_CONFIG_PATH=config/projects.yaml259260# Required only when PROJECT_THREADS_MODE=group261PROJECT_THREADS_CHAT_ID=-1001234567890262```263264In strict mode, only `/start` and `/sync_threads` work outside mapped project topics.265In private mode, `/start` auto-syncs project topics for your private bot chat.266To use topics with your bot, enable them in BotFather:267`Bot Settings -> Threaded mode`.268269> **Full reference:** See [docs/configuration.md](docs/configuration.md) and [`.env.example`](.env.example).270271### Finding Your Telegram User ID272273Message [@userinfobot](https://t.me/userinfobot) on Telegram -- it will reply with your user ID number.274275## Troubleshooting276277**Bot doesn't respond:**278- Check your `TELEGRAM_BOT_TOKEN` is correct279- Verify your user ID is in `ALLOWED_USERS`280- Ensure Claude Code CLI is installed and accessible281- Check bot logs with `make run-debug`282283**Claude integration not working:**284- SDK mode (default): Check `claude auth status` or verify `ANTHROPIC_API_KEY`285- CLI mode: Verify `claude --version` and `claude auth status`286- Check `CLAUDE_ALLOWED_TOOLS` includes necessary tools287288**High usage costs:**289- Adjust `CLAUDE_MAX_COST_PER_USER` to set spending limits290- Monitor usage with `/status`291- Use shorter, more focused requests292293## Security294295This bot implements defense-in-depth security:296297- **Access Control** -- Whitelist-based user authentication298- **Directory Isolation** -- Sandboxing to approved directories299- **Rate Limiting** -- Request and cost-based limits300- **Input Validation** -- Injection and path traversal protection301- **Webhook Authentication** -- GitHub HMAC-SHA256 and Bearer token verification302- **Audit Logging** -- Complete tracking of all user actions303304See [SECURITY.md](SECURITY.md) for details.305306## Development307308```bash309make dev # Install all dependencies310make test # Run tests with coverage311make lint # Black + isort + flake8 + mypy312make format # Auto-format code313make run-debug # Run with debug logging314```315316### Contributing3173181. Fork the repository3192. Create a feature branch: `git checkout -b feature/amazing-feature`3203. Make changes with tests: `make test && make lint`3214. Submit a Pull Request322323**Code standards:** Python 3.10+, Black formatting (88 chars), type hints required, pytest with >85% coverage.324325## License326327MIT License -- see [LICENSE](LICENSE).328329## Acknowledgments330331- [Claude](https://claude.ai) by Anthropic332- [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot)333
Full transparency — inspect the skill content before installing.