# claude-code-telegram

> Telegram bot that lets you chat with Claude Code about your projects from any device

- Repository: https://github.com/overwirehq/claude-code-telegram
- Category: Coding agents & dev tools
- Stars: 2,817 · Forks: 426 · Language: Python · License: not stated
- Experience: Some experience
- Page: https://ir.adyog.com/repos/overwirehq/claude-code-telegram/

Claude Code normally runs in a terminal on the machine where your code lives. This project puts a Telegram bot in front of it. You message the bot in plain language, and it passes the request to Claude Code, which works inside a directory you approved and sends back the result.

The bot runs on your computer or a server and uses the Claude Code SDK, with the CLI as a fallback. It saves a session for each user and project folder, so a conversation can resume where it stopped. Settings live in a .env file: your bot token, the approved directory and the Telegram user IDs allowed to use it.

Besides chat, it can react to outside events. A small API server takes GitHub webhooks, and a cron-style scheduler runs recurring tasks. Claude's answers are sent to the Telegram chats you list. It has two modes: a conversational default, and a classic mode with 13 terminal-like commands and buttons.

## What it does

- **Conversational agentic mode**: Just talk to Claude. A /verbose setting from 0 to 2 controls how much of its tool use and reasoning is shown while it works.
- **Per-project sessions**: Sessions are saved per user and project directory. /repo lists cloned repos and switches between them, and the session resumes.
- **Security controls**: A user whitelist, directory sandboxing with path traversal checks, rate limiting, per-user spending limits and audit logging.
- **Webhooks and scheduler**: Accepts GitHub webhooks (HMAC-SHA256) or generic Bearer-token calls, and runs cron-scheduled Claude tasks. Results go to Telegram chats.
- **Files, images and voice**: You can upload files and screenshots for Claude to look at, and send voice messages that are transcribed with Mistral Voxtral, OpenAI Whisper or a local whisper.cpp.

## What you could build

- Ask Claude to add error handling or a retry decorator to a file and run the tests, all from your phone.
- Clone a GitHub repo, review open issues, then create a branch and push a fix by chatting.
- Route GitHub push or pull request events through Claude to get automatic summaries or code reviews in Telegram.
- Schedule a daily code health check that posts its findings to a Telegram chat.
- Send a screenshot of a bug and ask Claude to investigate it in your project.

## Who it's for

Developers who already use Claude Code and want to reach it from their phone; you should be comfortable with Python, a .env file and creating a Telegram bot via BotFather.

## Get started

Install Python 3.11+ and the Claude Code CLI, and get a bot token from @BotFather. Install the bot, fill in the token, bot username, approved directory and your Telegram user ID in .env, then run it and message your bot.

```
uv tool install git+https://github.com/overwirehq/claude-code-telegram@v1.3.0
```
```
cp .env.example .env
```
```
make run
```

Tags: claude-code, telegram, remote-coding, python, automation