Claude Code Telegram Bot CLI
A Telegram bot for remote access to Claude Code: chat and the agent edits your project, with sessions and directory sandboxing.
- 2,823 ★ on the repository
- Last commit
Broad access
Why this level
- The bot lets allowed Telegram users drive Claude Code with reading, editing files and running commands in the project directory, and the bot token must be kept secret.
Install
- Works in
Manual install
uv tool install git+https://github.com/overwirehq/claude-code-telegram@v1.3.0The README's recommended method. After installation fill in `.env` and start with `make run`.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The bot lets allowed Telegram users drive Claude Code with reading, editing files and running commands in the project directory, and the bot token must be kept secret.
This is third-party code. Review the repository files before installing.
What it does
The bot connects Telegram to Claude Code so you can work on code from a chat on any device. A session persists per user and project, `/repo` switches directories and `/verbose` sets how much background work is shown. A terminal-style mode (`AGENTIC_MODE=false`) adds `/cd`, `/ls`, `/git` and buttons. Safety measures include an allowed users list, an `APPROVED_DIRECTORY` with path traversal prevention, rate limiting and an audit log. The bot also accepts GitHub webhooks, runs scheduled tasks, handles uploaded files and screenshots and transcribes voice messages.
Who it is for. Developers who want to hand a task to an agent from a phone and get the result in Telegram while the machine with the project runs at home or on a server.
Good fit when
- You want to look at a project's tests from a phone and ask the agent to fix a small bug.
- GitHub event notifications and nightly check results should arrive in Telegram.
- The project server has no graphical access and working with the agent is easier in a messenger.
- One bot serves several projects and you need to switch repositories quickly.
Not a fit when
- A project with secrets or closed code that cannot be trusted to a chain of Telegram and bot keys.
- You need every change reviewed before it is written: the bot works through Claude Code with rights on the directory.
- There is no Claude Code on the bot's machine: it drives an already installed CLI.
Example request
Connect the bot to `~/projects`, allow only my Telegram ID and show how to ask Claude from a phone to run the tests.Limitations
Python 3.11 or newer, an installed Claude Code CLI and a bot token from BotFather are required. `.env` sets `TELEGRAM_BOT_TOKEN`, `APPROVED_DIRECTORY` and `ALLOWED_USERS` with numeric IDs of allowed users. Anyone you allow gets control of Claude Code with access to files and commands inside that directory, so keep the list short. The author recommends installing from a release tag rather than `main`. GitHub shows no license although the README carries an MIT badge.
How to disable. Stop the bot (`Ctrl+C` or stopping the service), revoke the token with `/revoke` at @BotFather, uninstall the package with `uv tool uninstall` and delete the `.env` file.
FAQ
How do I install the bot?
With `uv tool install git+https://github.com/overwirehq/claude-code-telegram@v1.3.0` or `pip install` from a release tag. For development there is `make dev` with Poetry.
What is the minimum configuration?
`TELEGRAM_BOT_TOKEN`, `TELEGRAM_BOT_USERNAME`, `APPROVED_DIRECTORY` and `ALLOWED_USERS` in the `.env` file.
How do the modes differ?
Agentic mode is the default: you just write. Classic mode (`AGENTIC_MODE=false`) adds 13 commands with buttons, directory navigation and git commands.
Can I get notifications?
Yes, with `ENABLE_API_SERVER=true` and `ENABLE_SCHEDULER=true` the bot accepts GitHub webhooks and runs scheduled tasks.
How is access protected?
An allowed users list, an optional token, rate limiting, protection against leaving `APPROVED_DIRECTORY` and an audit log.
Discussion
No questions or reviews yet.
Related
CLI toolsA Telegram bot for OpenCode: send coding tasks, watch progress and switch models from your phone while OpenCode keeps running on your own computer
Claude Chat Mobile opens the same Claude Code session on your computer from a phone: approvals, questions and lock-screen pushes.
Streams Claude Code hidden thinking, tool calls and subagents to a separate terminal with a live session tree
Xylocopa is a visual orchestrator for Claude Code agents: GTD tasks, parallel agents in git worktrees, phone approvals.
A set of slash commands, skills and subagents for Claude Code: review, tests, security, releases, docs and GitHub to Linear sync
Shared Claude Code settings for a team: hooks against dangerous commands, a check before finishing and skills from spec to review
README in short
The README describes a Telegram bot on top of Claude Code with two modes, directory protection, webhooks and scheduling. It installs from a release tag through `uv` or `pip`.