claude-code-telegram: Remote Claude Code Access Through a Telegram Bot

What claude-code-telegram actually solves

Claude Code is a terminal tool. That is fine at a desk and awkward everywhere else: on a phone, on a tablet, or from a machine that is not the one holding the repository. claude-code-telegram wraps the Claude Code CLI and the claude-agent-sdk behind a Telegram bot, so the prompt surface becomes a chat window instead of a shell.

The intended user is a developer who already has Claude Code working on a server or workstation and wants to reach it from Telegram. The README's own demo shows the shape of that: you ask the bot to add error handling to src/api.py, it reads the file, proposes changes, and then runs pytest when you ask it to verify. Nothing in that loop requires SSH.

The second audience is automation. The README describes webhooks for GitHub events, a cron-style scheduler for recurring tasks, and a notification service that delivers agent responses to configured Telegram chats. That turns the bot into a small event router for Claude, not just a chat front end. Whether that is useful depends on whether you want an agent reacting to your repository events, which is a different proposition from wanting a mobile terminal.

Two modes, one agent loop

The bot ships with two interaction models, and the default is the conversational one. In agentic mode you send plain language and Claude decides which tools to call. The README shows the bot streaming tool activity back as it works: a read, a directory listing, an edit, then a pytest run. Verbosity is controlled with /verbose and takes 0, 1 or 2. Level 0 shows only the final response, level 1 (the default) shows tool names plus short reasoning snippets, and level 2 adds tool inputs and longer reasoning text. That three-level scale is the right shape for a chat transport, where a full tool trace is unreadable on a phone but a silent bot is worse.

Classic mode is a different product. Setting AGENTIC_MODE=false swaps in a 13-command interface with directory navigation, inline keyboards, quick actions, git integration and session export. The commands listed in the README are /start, /help, /new, /continue, /end, /status, /cd, /ls, /pwd, /projects, /export, /actions and /git. If you have used a terminal-based chatbot before, this mode will be familiar; if you have not, the agentic mode is the one to start with.

Session persistence is per user and per project directory, which is the detail that makes the whole thing usable. Switching directories with /repo in agentic mode or /cd in classic mode resumes the matching session rather than starting a blank conversation. The README notes that sessions auto-resume on a directory switch.

Installing claude-code-telegram and sending a first prompt

The README lists three prerequisites: Python 3.11 or newer, the Claude Code CLI, and a Telegram bot token from @BotFather. The pyproject.toml confirms requires-python >=3.11 and declares the console script claude-telegram-bot pointing at src.main:run.

The README's recommended install is from a release tag. Note that the example it gives uses v1.3.0, while the current release listed in the repository is v1.7.0; substitute the tag you actually want rather than copying the README literally.

uv tool install git+https://github.com/overwirehq/[email protected]

If you prefer pip, the README gives the equivalent form, and a @latest variant for tracking the newest stable release. The README explicitly warns against installing from main for stability.

Configuration starts from the example environment file. Four values are marked as the minimum required.

cp .env.example .env

TELEGRAM_BOT_TOKEN=1234567890:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TELEGRAM_BOT_USERNAME=my_claude_bot
APPROVED_DIRECTORY=/Users/yourname/projects
ALLOWED_USERS=123456789

APPROVED_DIRECTORY is the sandbox root, so it should be the parent of the projects you want reachable, not your home directory. ALLOWED_USERS is a comma-separated list of Telegram user IDs; the .env.example warns that leaving it empty allows all users and is not recommended for production. Then run it.

make run

make run-debug is the same with debug logging. Once the process is up, message the bot on Telegram. The first thing worth sending is a question about the project structure, because it exercises the read and list tools without modifying anything, and the bot's streamed tool output tells you immediately whether the sandbox root and the Claude authentication are both correct.

Where the security model is thinner than it looks

The README advertises multi-layer authentication, directory sandboxing with path traversal prevention, rate limiting via a token bucket, and audit logging. Those are real components, and the .env.example exposes the switches for them, including ENABLE_TOKEN_AUTH with AUTH_TOKEN_SECRET generated by openssl rand -hex 32.

The problem is the escape hatch. DISABLE_SECURITY_PATTERNS is documented as disabling dangerous pattern validation in path and command checks, with the warning that it enables characters like pipes and redirections in validated input. There is a second switch, described in the same file, that disables Claude tool validation by allow or disallow list. Both are described as trusted-environment-only settings, and both invert the security posture the README leads with. A bot whose entire purpose is executing commands chosen by a language model should not have a one-line config that removes the command validation layer, even behind a warning comment. If you deploy this, treat those two keys as off-limits and check them after any configuration change.

The broader failure mode is the threat model itself. The bot runs Claude Code against APPROVED_DIRECTORY with whatever credentials the host has, including a gh CLI session if you follow the README's GitHub workflow section. An ALLOWED_USERS list protects the Telegram side. It does nothing about what the agent can reach once it is running. Point APPROVED_DIRECTORY at a directory that does not contain .env files, SSH keys or cloud credentials, and do not rely on the sandbox to compensate for a bad choice of root.

How it compares with running Claude Code over SSH

The obvious alternative is not another bot. It is SSH plus tmux, or a plain Claude Code session on a remote host with a mobile SSH client. That gives you the real terminal, the full CLI, and no third party in the loop. The trade-off is everything the bot adds: no session persistence keyed to a project directory, no inline quick-action buttons, no webhook or scheduler integration, and a mobile terminal experience that is genuinely unpleasant for long prompts.

Within the same category, the closest comparison is a generic Telegram-to-shell bridge, a bot that forwards commands to a shell and returns stdout. Those are simpler and easier to audit, and they do not require Claude Code at all. They also do not understand your repository: no tool streaming, no per-project session memory, no awareness that a follow-up question refers to the file edited two messages ago. claude-code-telegram's value is specifically the Claude Code integration, and if you strip that out you are left with a worse shell.

The event-driven features are where the project diverges from both. A generic bridge cannot route a GitHub push event through an agent and post a summary to a chat. The README gates that behind ENABLE_API_SERVER=true and ENABLE_SCHEDULER=true, with the webhook server using GitHub HMAC-SHA256 verification and generic Bearer token auth. That is a meaningfully different tool from a remote terminal, and it is the part most likely to justify the setup cost.

Release cadence, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-11. Releases tell an uneven story: v1.6.0 landed on 2026-03-30, then v1.6.1 and v1.7.0 both arrived on 2026-09-11. That is a long quiet stretch followed by two releases in one day, which is worth knowing before you plan around a predictable cadence.

The Makefile exposes the release machinery directly: bump-patch, bump-minor and bump-major each bump the version, commit and tag, and release pushes the tag to trigger the release workflow. The pyproject.toml carries version = "1.7.0", matching the newest release. For upgrades, the README's instruction to install from a tagged release rather than main is the practical guidance, and the repository includes a CHANGELOG.md. The README does not document a rollback procedure, and it does not describe database migration rollback either, which matters because the project uses SQLite persistence with migrations.

On licensing: pyproject.toml declares license = "MIT" and the README carries an MIT badge, so the project is MIT-licensed. The repository metadata does not list a licence, which is a discrepancy worth resolving from the LICENSE file itself before you rely on it. MIT is permissive, but note that the bot depends on claude-agent-sdk and anthropic, and your use of Claude itself is governed by Anthropic's terms, not by this project's licence. That is not legal advice; read the actual files.

Editorial conclusion

Adopt claude-code-telegram if you already run Claude Code on a machine you can leave on, want conversational access to a bounded project directory from a phone, and are comfortable with software the package metadata labels Alpha. Do not adopt it if you need a documented upgrade path, a stable API surface, or unattended access to a directory containing credentials. Before installing, verify three things: that Claude Code CLI is installed and authenticated on the host, that APPROVED_DIRECTORY points at a directory you are willing to expose to remote prompts, and that ALLOWED_USERS is populated with your Telegram user ID rather than left empty.

Frequently asked questions

Official sources

1. Issues
2. overwirehq/claude-code-telegram on GitHub
3. README
4. Releases