Skip to content
Back to search

claude-telegram-bot-bridge

A lightweight Telegram bot that bridges Claude Code to any local folder, with autostart support for remote mobile development.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/terranc--claude-telegram-bot-bridge/badge.svg)](/listings/terranc--claude-telegram-bot-bridge)

HTML

<a href="/listings/terranc--claude-telegram-bot-bridge"><img src="/api/listings/terranc--claude-telegram-bot-bridge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/terranc/claude-telegram-bot-bridge
cd claude-telegram-bot-bridge
claude

Then run `/setup`. Claude Code will handle everything: system checks, bot token collection, dependency installation, and configuration.

> **Note:** Commands starting with `/` (like `/setup`) are [Claude Code skills](https://code.claude.com/docs/en/skills). Type them in the `claude` CLI prompt, not in your regular terminal.

Once setup is complete, start the bot:

./start.sh --path /path/to/your/project

<details> <summary>Alternative: Direct installation script</summary>

If you prefer not to use Claude Code, run the installation script directly:

git clone https://github.com/terranc/claude-telegram-bot-bridge
cd claude-telegram-bot-bridge
./setup.sh

Then start the bot:

./start.sh --path /path/to/your/project

</details>

Common Commands

./start.sh --path /path/to/project              # Start (foreground)
./start.sh --path /path/to/project -d           # Start (daemon/background)
./start.sh --path /path/to/project --debug      # Debug mode
./start.sh --path /path/to/project --status     # Check status
./start.sh --path /path/to/project --stop       # Stop
./start.sh --path /path/to/project --upgrade    # Update to latest version
./start.sh --path /path/to/project --install    # macOS only: install startup service
./start.sh --path /path/to/project --uninstall  # macOS only: remove startup service

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 375 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Claude Telegram Bot Bridge
  2. [中文文档](README-zh.md)
  3. Turn your Telegram into a remote Claude Code terminal. Chat with Claude, run skills, edit code, search files — all from your phone, anywhere.
  4. ## The Problem
  5. Claude Code is powerful, but it's bound to your terminal. When you step away from your computer — commuting, in a meeting, or just on the couch — you lose access. You can't quickly check a build result, ask Claude to fix a bug, or run a skill command until you're back at your desk.
  6. Solutions like [OpenClaw](https://github.com/anthropics/openclaw) exist, but they come with trade-offs: a full web stack to deploy and maintain, potential security concerns with exposing your dev environment through a web interface, and heavyweight infrastructure that feels like overkill when you just want to quickly send Claude a message from your phone.
  7. This bot takes a different approach — **lightweight, zero-infrastructure, secure by default**. It connects Claude Code SDK to a Telegram bot (a messaging app you already have), so you get a persistent, always-on Claude Code session you can talk to from anywhere. No web server, no ports to expose, no extra auth layer. Start it once for a project directory, and it runs as a daemon in the background — surviving crashes, rebooting with your Mac, managing its own dependencies. Telegram itself handles authentication, encryption, and push notifications.
  8. ## Features
  9. ### Screenshots
  10. | | | |
  11. |:---:|:---:|:---:|
  12. | ![Streaming](docs/screenshots/b922c1374d20c13f941d64955789d379.jpg) | ![Voice](docs/screenshots/1cd0c60ba52f0ef2081a8ebc69a486c5.jpg) | ![Code](docs/screenshots/code-editing.jpg) |
  13. **Core**
  14. - Chat with Claude directly in Telegram, powered by Claude Code SDK
  15. - Invoke any Claude Code skill (`/skill <name>`) or slash command (`/command <cmd>`) remotely
  16. - Switch between Sonnet, Opus, and Haiku on the fly via `/model`
  17. - Resume previous conversations with `/resume` and browse session history
  18. - View recent conversation history with `/history` — displays last 5 messages from current session
  19. - Revert to any previous message with `/revert` — choose from 5 modes: full restore (code + conversation), conversation only, code only, summarize from point, or cancel
  20. **Smart Interaction**
  21. - Progressive streaming: AI responses update in real-time as Claude thinks, not after completion
  22. - Claude's numbered options auto-convert to Telegram inline keyboard buttons — just tap to choose
  23. - File paths (images, PDFs, etc.) in Claude's responses are automatically sent as photos or documents
  24. - Native Telegram voice messages: auto-download, format detection/conversion (OGG/AMR → MP3), Whisper transcription, then forwarded to Claude
  25. - Per-user dedicated SDK streams — low latency, concurrent message support (up to 3 per user)
  26. - Priority `/stop` command: immediately cancels running tasks and voice transcription, even when message queue is full
  27. - Priority `/revert` command: bypasses message queue limit, cancels active operations, restores conversation state to any previous point
  28. **Security**
  29. - File access inside the project directory is auto-allowed
  30. - Access outside the project triggers inline-button confirmation in Telegram
  31. - User whitelist via `ALLOWED_USER_IDS`
  32. - Stale messages (>20 min) are silently dropped
  33. **Operations**
  34. - Daemon mode with auto-restart on crash (stops after 5 rapid crashes in 60s)
  35. - One-command macOS launchd auto-start on boot (`--install`) with inherited `PATH`/`HOME`
  36. - Auto-update check on startup — notifies when new version available
  37. - One-command upgrade (`--upgrade`) — pulls latest code and reinstalls dependencies
  38. - MD5-based dependency caching — skips reinstall when `requirements.txt` is unchanged
  39. - Auto venv creation, 14-day log rotation, crash logging with exit codes
  40. - Dedicated polling HTTP client with proxy-aware HTTP/1.1 settings for better recovery after network changes
  41. ## Prerequisites
  42. - **Python 3.11+**
  43. - **Claude CLI** — installed and in `$PATH`, or specify via `CLAUDE_CLI_PATH`
  44. - **Telegram Bot Token** — from [@BotFather](https://t.me/BotFather)
  45. - **ffmpeg** — required for audio format conversion
  46. - **OpenAI API Key** — required for Whisper transcription (`OPENAI_API_KEY`)
  47. ## Platform Support
  48. - **macOS** — fully supported, including `--install` / `--uninstall`
  49. - **WSL (Ubuntu/Debian-style Linux userland)** — supported for foreground run, `--daemon`, `--status`, and `--stop`
  50. - **Native Windows (PowerShell / CMD)** — not supported
  51. ## Quick Start
  52. ```bash
  53. git clone https://github.com/terranc/claude-telegram-bot-bridge
  54. cd claude-telegram-bot-bridge
  55. claude
  56. ```
  57. Then run `/setup`. Claude Code will handle everything: system checks, bot token collection, dependency installation, and configuration.
  58. > **Note:** Commands starting with `/` (like `/setup`) are [Claude Code skills](https://code.claude.com/docs/en/skills). Type them in the `claude` CLI prompt, not in your regular terminal.
  59. Once setup is complete, start the bot:
  60. ```bash
  61. ./start.sh --path /path/to/your/project
  62. ```
  63. <details>
  64. <summary>Alternative: Direct installation script</summary>
  65. If you prefer not to use Claude Code, run the installation script directly:
  66. ```bash
  67. git clone https://github.com/terranc/claude-telegram-bot-bridge
  68. cd claude-telegram-bot-bridge
  69. ./setup.sh
  70. ```
  71. Then start the bot:
  72. ```bash
  73. ./start.sh --path /path/to/your/project
  74. ```
  75. </details>
  76. ### Common Commands
  77. ```bash
  78. ./start.sh --path /path/to/project # Start (foreground)
  79. ./start.sh --path /path/to/project -d # Start (daemon/background)
  80. ./start.sh --path /path/to/project --debug # Debug mode
  81. ./start.sh --path /path/to/project --status # Check status
  82. ./start.sh --path /path/to/project --stop # Stop
  83. ./start.sh --path /path/to/project --upgrade # Update to latest version
  84. ./start.sh --path /path/to/project --install # macOS only: install startup service
  85. ./start.sh --path /path/to/project --uninstall # macOS only: remove startup service
  86. ```
  87. ## Usage Examples
  88. ### Fix a bug from your phone
  89. You're away from your desk and a teammate reports a bug. Open Telegram:
  90. ```
  91. You: login page crashes when email contains a plus sign
  92. Claude: I found the issue in src/auth/validator.ts:42 — the regex
  93. doesn't escape the + character. Fixed and the test passes now.
  94. ```
  95. ### Run a skill remotely
  96. ```
  97. You: /skill commit
  98. Claude: Created commit: fix(auth): escape special characters in email validation
  99. ```
  100. ### Send a voice message
  101. ```
  102. You: [send Telegram voice message]
  103. Bot: 🎤 Voice: summarize yesterday's git diff
  104. Claude: Here is a summary of yesterday's changes...
  105. ```
  106. ### Resume yesterday's work
  107. ```
  108. You: /resume
  109. Bot: 1. Refactoring auth module — 2 hours ago
  110. 2. Adding dark mode — yesterday
  111. 3. API rate limiting — 3 days ago
  112. You: 1
  113. Claude: Resuming session... [continues from where you left off]
  114. ```
  115. ### Check recent conversation history
  116. ```
  117. You: /history
  118. Bot: 📜 Recent History (last 5 messages)
  119. 🧑 User [2026-03-05 14:23:15]
  120. fix the login bug
  121. 🤖 Assistant [2026-03-05 14:23:18]
  122. I found the issue in src/auth/validator.ts:42...
  123. 🧑 User [2026-03-05 14:25:30]
  124. add a test for this
  125. 🤖 Assistant [2026-03-05 14:25:35]
  126. Added test in tests/auth.test.ts...
  127. ```
  128. ### Revert to a previous conversation state
  129. ```
  130. You: /revert
  131. Bot: 🔄 Select a message to revert to:
  132. [Shows paginated list of last 50 messages with inline buttons]
  133. You: [Tap on a message]
  134. Bot: Choose revert mode:
  135. 1️⃣ Restore code and conversation
  136. 2️⃣ Restore conversation only
  137. 3️⃣ Restore code only
  138. 4️⃣ Summarize from here
  139. 5️⃣ Cancel
  140. You: [Tap "Restore code and conversation"]
  141. Bot: ✅ Reverted to message #42. Conversation and code state restored.
  142. ```
  143. You: 1
  144. Bot: Switched to session: Refactoring auth module
  145. You: where did we leave off?
  146. Claude: We finished extracting the JWT logic into a separate service.
  147. Still remaining: updating the middleware to use the new service...
  148. ```
  149. ### Switch models mid-conversation
  150. ```
  151. You: /model haiku
  152. Bot: Switched to Claude Haiku
  153. You: summarize the changes in src/api/ from the last 3 commits
  154. Claude: ...
  155. ```
  156. ### Let the bot run 24/7
  157. ```bash
  158. # Install as macOS startup service — survives reboots
  159. ./start.sh --path ~/my-project --install
  160. # The generated launchd plist preserves PATH and HOME
  161. # so Claude CLI and proxy settings still resolve at boot
  162. # Check status anytime
  163. ./start.sh --path ~/my-project --status
  164. # 🟢 Bot is running (PID: 12345)
  165. # Uninstall when done
  166. ./start.sh --path ~/my-project --uninstall
  167. ```
  168. ## Bot Commands
  169. | Command | Description |
  170. |---|---|
  171. | `/start` | Start a conversation |
  172. | `/new` | Start a new session (clears current stream and cancels ongoing streaming) |
  173. | `/model` | Switch model (Sonnet / Opus / Haiku) |
  174. | `/resume` | Browse and resume a previous session (shows progress summary with last assistant message) |
  175. | `/stop` | Interrupt execution immediately (bypasses queue, cancels active task) |
  176. | `/history` | View recent conversation history |
  177. | `/revert` | Revert to a previous conversation state (browse history, select message, choose restore mode) |
  178. | `/skills` | List available Claude Code skills |
  179. | `/skill <name> [args]` | Execute a skill command |
  180. | `/command <cmd> [args]` | Execute a Claude Code slash command |
  181. Any unrecognized `/command` is also forwarded as a skill invocation.
  182. ## Environment Variables
  183. | Variable | Required | Default | Description |
  184. |---|---|---|---|
  185. | `TELEGRAM_BOT_TOKEN` | Yes | — | Telegram Bot API token |
  186. | `ALLOWED_USER_IDS` | No | *(allow all)* | Comma-separated user ID whitelist |
  187. | `CLAUDE_CLI_PATH` | No | *(auto-detect)* | Absolute path to Claude CLI binary |
  188. | `CLAUDE_SETTINGS_PATH` | No | `~/.claude/settings.json` | Path to Claude Code settings file |
  189. | `CLAUDE_PROCESS_TIMEOUT` | No | `600` | SDK timeout in seconds |
  190. | `AUTO_NEW_SESSION_AFTER_HOURS` | No | `24` | Auto-start new session after N hours of inactivity; set to `0`/`false`/`off` to disable |
  191. | `DRAFT_UPDATE_MIN_CHARS` | No | `150` | Minimum characters before streaming draft update |
  192. | `DRAFT_UPDATE_INTERVAL` | No | `1.0` | Minimum seconds between streaming draft updates |
  193. | `ENABLE_STREAMING_TOOL_CALLS` | No | `false` | Show Claude tool calls in Telegram streaming messages |
  194. | `TRANSCRIPTION_PROVIDER` | No | `whisper` | Voice transcription provider: `whisper` or `volcengine` |
  195. | `OPENAI_API_KEY` | Voice only | — | OpenAI API key for Whisper transcription |
  196. | `OPENAI_BASE_URL` | No | *(official OpenAI API)* | OpenAI-compatible Whisper endpoint base URL |
  197. | `WHISPER_MODEL` | No | `whisper-1` | Whisper model name |
  198. | `VOLCENGINE_APP_ID` | Volcengine only | — | Volcengine ASR `X-Api-App-Key` |
  199. | `VOLCENGINE_TOKEN` | Volcengine only | — | Volcengine ASR `X-Api-Access-Key` |
  200. | `VOLCENGINE_ACCESS_KEY` | Volcengine only | — | Volcengine TOS Access Key |
  201. | `VOLCENGINE_SECRET_ACCESS_KEY` | Volcengine only | — | Volcengine TOS Secret Access Key (create at `https://console.volcengine.com/iam/keymanage`) |
  202. | `VOLCENGINE_TOS_BUCKET_NAME` | Volcengine only | — | TOS bucket used for staging Telegram voice files |
  203. | `VOLCENGINE_TOS_ENDPOINT` | Volcengine only | — | TOS endpoint (must match your bucket region, e.g. `https://tos-cn-shanghai.volces.com`) |
  204. | `VOLCENGINE_TOS_REGION` | No | `cn-beijing` | TOS region used by SDK signing |
  205. | `FFMPEG_PATH` | No | *(auto-detect)* | Absolute path to ffmpeg binary |
  206. | `VOICE_REPLY_PERSONA` | No | `Tingting` | Persona name used by voice reply mode |
  207. | `LOG_LEVEL` | No | `INFO` | Logging level |
  208. | `PROXY_URL` | No | — | HTTP proxy; auto-configures `http_proxy`/`https_proxy`/`all_proxy` |
  209. ## Voice Transcription Channels
  210. - Default channel is `whisper`.
  211. - To use Volcengine file-fast ASR, set:
  212. - `TRANSCRIPTION_PROVIDER=volcengine`
  213. - `VOLCENGINE_APP_ID`
  214. - `VOLCENGINE_TOKEN`
  215. - `VOLCENGINE_ACCESS_KEY`
  216. - `VOLCENGINE_SECRET_ACCESS_KEY`
  217. - `VOLCENGINE_TOS_BUCKET_NAME`
  218. - `VOLCENGINE_TOS_ENDPOINT`
  219. - Secret Access Key must be created in Volcengine IAM key management:
  220. - `https://console.volcengine.com/iam/keymanage`
  221. - In Volcengine mode, the bot now uses `download -> TOS upload -> signed TOS URL -> ASR`.
  222. ## Voice Reply Mode (macOS)
  223. - User voice messages switch reply mode to voice automatically.
  224. - User text messages switch reply mode back to text.
  225. - In voice mode:
  226. - `>1000` Chinese characters or `>1000` English words: text only (voice mode is kept)
  227. - `>300` characters (and not over 1000 threshold): send voice + text
  228. - Otherwise: send voice only
  229. - Voice transcription preview (`🎤 Voice: ...`) is bundled with the final reply:
  230. - if text is sent, preview is merged at the top of that same text message
  231. - if voice-only reply is sent, the bot sends preview text first, then voice
  232. - The bot uses macOS `say` for synthesis, then converts output to Telegram-compatible `ogg/opus` via `ffmpeg`.
  233. - `VOICE_REPLY_PERSONA` should be a real macOS voice name from `say -v ?`.
  234. - If `VOICE_REPLY_PERSONA` is unavailable on current system, the bot sends a friendly error and falls back to text for that reply.
  235. - Set `VOICE_REPLY_PERSONA` to the first-column name shown by `say -v ?`.
  236. - Example:
  237. - `VOICE_REPLY_PERSONA=Tingting`
  238. ## ffmpeg Installation
  239. Install ffmpeg before enabling voice messages:
  240. - macOS (Homebrew): `brew install ffmpeg`
  241. - Ubuntu/Debian or WSL: `sudo apt-get update && sudo apt-get install -y ffmpeg`
  242. Then verify:
  243. ```bash
  244. ffmpeg -version
  245. ```
  246. ## Whisper Cost Notes
  247. Voice transcription uses OpenAI Whisper API (`whisper-1`) and incurs usage-based charges.
  248. Current reference pricing is about **$0.006/minute** of audio. Check OpenAI pricing for latest values.
  249. ## Security
  250. - `--path` sets the `PROJECT_ROOT` — the sandbox boundary for all file operations.
  251. - File access within `PROJECT_ROOT` is auto-allowed. Outside access requires user confirmation via inline buttons.
  252. - Bot output referencing external files requires confirmation before sending.
  253. - All runtime data stays under `PROJECT_ROOT/.telegram_bot/`.
  254. ## Lifecycle Management
  255. ```bash
  256. ./start.sh --path /path/to/project --status # Check if running
  257. ./start.sh --path /path/to/project --stop # Stop
  258. ./start.sh --path /path/to/project --install # macOS only: launchd auto-start on boot
  259. ./start.sh --path /path/to/project --uninstall # macOS only: remove auto-start
  260. ```
  261. The daemon auto-restarts on crash, logs each crash with exit code and uptime, and stops restarting after 5 rapid crashes in 60 seconds.
  262. When `PROXY_URL` is set, both regular Bot API calls and long-polling requests use proxy-aware HTTP/1.1 clients. This helps the bot recover more reliably after laptop sleep, network handoffs, or proxy reconnects.
  263. ### macOS Full Disk Access
  264. If your project directory is located in `~/Documents`, `~/Desktop`, or `~/Downloads`, macOS privacy protection will block launchd from reading files in those directories. This causes `--install` to fail with exit code 78 (EX_CONFIG).
  265. **Solution**: Add `/bin/bash` to Full Disk Access:
  266. 1. Open **System Settings** → **Privacy & Security** → **Full Disk Access**
  267. 2. Click the **+** button
  268. 3. Press `Cmd + Shift + G` and type `/bin/bash`
  269. 4. Select `bash` and confirm
  270. After this, `--install` will work correctly in protected directories.
  271. ## Debugging
  272. ```bash
  273. ./start.sh --path /path/to/project --debug
  274. # Or: BOT_DEBUG=1 python -m telegram_bot --path .
  275. ```
  276. Enables full console logging, per-session chat logs, and SDK tool call tracing.
  277. ## License
  278. MIT
  279. ## Star History
  280. [![Star History Chart](https://api.star-history.com/svg?repos=terranc/claude-telegram-bot-bridge&type=Date)](https://star-history.com/#terranc/claude-telegram-bot-bridge&Date)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.