@tekmidian/telex
Advanced tools
Telegram MCP bridge for Claude Code — bidirectional self-chat via MTProto
Your phone is now a Claude Code terminal - via Telegram. Send a message to your Saved Messages, Claude gets it. Claude responds, you see it on Telegram. Text, images, voice notes - in both directions.
Dictate a voice note while driving and Claude starts coding. Send an image from your phone and Claude interprets it. Get spoken responses back in any of 28 voices - all synthesized locally, nothing leaves your machine. Take complete control of your computer using /t to open and manage any number of terminal sessions. Manage multiple Claude sessions from your couch with /s, switch between them, or /kill a stuck one and restart it fresh. Take screenshots of any session using /ss and have the screenshot sent to you via Telegram.
One command to set up. Zero cloud dependencies for voice. Works with any Telegram account.
Telex is a thin adapter plugin for the AIBroker hub. It does one thing: maintain the GramJS MTProto connection to Telegram and pass messages in and out. All the intelligence - commands, session management, TTS/STT, screenshots, image generation, vision, and MCP tools - lives in the AIBroker daemon.
Telex registers with AIBroker on startup via a Unix Domain Socket. If AIBroker is not running, Telex will not function.
AIBroker Hub (daemon, launchd: com.aibroker.daemon)
- Commands, session management, TTS/STT, screenshots, image gen
- Unified MCP server (whatsapp_*, telegram_*, pailot_*, aibroker_*)
- IPC socket: /tmp/aibroker.sock
Whazaa adapter (WhatsApp, launchd: com.whazaa.watcher)
Baileys connection only
Telex adapter (this package, launchd: com.telex.watcher)
GramJS MTProto connection only
PAILot (iOS app, WebSocket on port 8765)
Telex heartbeats every 30 seconds with a ping to the hub. All telegram_* MCP tools are served by AIBroker's unified MCP server - not by Telex itself.
Tell Claude Code:
Clone https://github.com/mnott/Telex and set it up for me
Claude clones the repo, finds the setup skill, and handles everything autonomously - prerequisites, build, MCP config, adapter daemon, and Telegram authentication. The only thing you do is enter your phone number and verification code when prompted.
If you prefer a traditional install without cloning:
npx -y @tekmidian/telex setup
This will:
~/.claude.json~/.telex/auth/ on first authenticationRestart Claude Code. Telex connects automatically from now on.
git clone https://github.com/mnott/Telex.git
cd Telex
npm install
npm run build
Then tell Claude to set it up from the local clone.
TELEGRAM_API_ID and TELEGRAM_API_HASH) from my.telegram.orgInstall ffmpeg and Whisper via Homebrew:
brew install ffmpeg
pip install openai-whisper
api_id (number) and api_hash (string)export TELEGRAM_API_ID=12345678
export TELEGRAM_API_HASH=abcdef1234567890abcdef1234567890
Add these to your ~/.zshrc or ~/.bashrc for persistence. The AIBroker daemon also reads these from ~/.aibroker/env when running as a launchd service.
Once Telex is set up, you talk to Claude in plain language. You never need to know about tool names or parameters - just say what you want.
Tell Claude what to say and to whom:
If you don't say who to send it to, Claude sends to your Telegram Saved Messages - useful for notes to yourself.
Claude can send a Telegram voice note instead of a text message:
You can choose whose voice to use:
See the full voice list in the telegram_tts section below.
Claude can speak out loud through your Mac - no Telegram needed:
Put Claude into persistent voice mode so every response comes back as audio automatically.
Voice mode is perfect for driving, cooking, or any time you can't look at a screen.
Send /ss from your phone and the hub captures the active Claude session's iTerm2 window and sends it back to Telegram as an image.
Control your Claude sessions from Telegram:
/s - see a list of your active Claude sessions/2 - switch to session 2/2 Cooking Project - switch to session 2 and name it/n - create a new Claude sessionThe following telegram_* tools are served by the AIBroker unified MCP server. They cover the Telegram transport layer:
| Tool | Description |
|---|---|
telegram_status | Check Telegram connection status |
telegram_send | Send a text message (to Saved Messages or any contact) |
telegram_tts | Send a voice note via TTS (Kokoro, local synthesis) |
telegram_send_file | Send a file (with optional caption and prettify) |
telegram_receive | Drain buffered incoming messages |
telegram_wait | Long-poll for incoming messages (up to timeout) |
telegram_login | Trigger fresh Telegram authentication |
telegram_contacts | List Telegram contacts |
telegram_chats | List Telegram chats |
telegram_history | Get message history for a chat |
telegram_voice_config | Get or set voice/TTS configuration |
telegram_speak | Play TTS locally through Mac speakers |
Session management tools (rename, restart, switch, discover, end session, command) are provided as aibroker_* tools by the AIBroker hub and apply across all adapters - not just Telegram.
Takes no parameters. Returns connection state, authenticated phone number, and adapter uptime.
Sends a text message to your Saved Messages or any contact.
Parameters:
message (required) - the text to sendrecipient (optional) - username, phone number, chat ID, or display name; omit for Saved Messagesvoice (optional, boolean) - if true, send as a TTS voice note instead of textConverts text to speech and sends it as a Telegram voice note.
ffmpeg for WAV to OGG Opus conversionParameters:
text (required) - text to convert to speechrecipient (optional) - username, phone number, chat ID, or display name; omit for Saved Messagesvoice (optional) - voice name from the table below; omit to use the configured defaultAvailable voices (28 total):
| Category | Voices |
|---|---|
| American Female | af_heart, af_alloy, af_aoede, af_bella, af_jessica, af_kore, af_nicole, af_nova, af_river, af_sarah, af_sky |
| American Male | am_adam, am_echo, am_eric, am_fenrir, am_liam, am_michael, am_onyx, am_puck, am_santa |
| British Female | bf_alice, bf_emma, bf_isabella, bf_lily |
| British Male | bm_daniel, bm_fable, bm_george, bm_lewis |
Default voice: bm_fable
Sends a file as a Telegram document, or optionally as inline formatted messages.
Parameters:
filePath (required) - absolute path to the filerecipient (optional) - username, phone number, chat ID, or display name; omit for Saved Messagescaption (optional) - caption text to attach to the fileprettify (optional, boolean) - if true, send the file contents as formatted inline Telegram messages rather than a document attachment; useful for markdown files you want to read in chatDrains all messages buffered for the current session since the last call.
Parameters:
from (optional) - omit for Saved Messages only, "all" for all sources, or a chat ID/name to filterEfficient alternative to polling. Blocks until a message arrives or the timeout expires.
Parameters:
timeoutMs (optional) - max wait in milliseconds; default 120000, max 300000Use this when you want Claude to wait while you compose a reply:
"Wait for my next Telegram message before continuing."
Takes no parameters. Triggers a fresh Telegram authentication flow. Use this if the session has expired or credentials have been revoked.
Lists your Telegram contacts.
Parameters:
search (optional) - filter by name or usernamelimit (optional) - maximum results to returnLists your Telegram chats (groups, channels, and direct messages).
Parameters:
search (optional) - filter by chat namelimit (optional, default 50) - maximum results to returnChat IDs returned here can be passed directly to telegram_history.
Fetches message history for a chat.
Parameters:
chatId (required) - chat ID, username, or 'me' for Saved Messagescount (optional, default 20) - number of messages to return (most recent first)Gets or sets the voice mode configuration. Configuration is persisted and survives adapter restarts.
Parameters:
action (required) - 'get' to read current config, 'set' to update itdefaultVoice (optional) - default voice name (e.g. 'bm_fable')voiceMode (optional, boolean) - true to enable automatic voice responseslocalMode (optional, boolean) - when true and voiceMode is true, use telegram_speak (Mac speakers) instead of telegram_tts (Telegram voice notes)personas (optional) - map of names to voice IDs (e.g. {"Nicole": "af_nicole", "George": "bm_george"})Default personas: Nicole -> af_nicole, George -> bm_george, Daniel -> bm_daniel, Fable -> bm_fable
Same TTS engine as telegram_tts, but plays audio through the Mac's speakers instead of sending a Telegram voice note. No Telegram connection required. Audio plays in the background without blocking other operations.
Parameters:
text (required) - text to speak aloudvoice (optional) - voice name (same list as telegram_tts); omit to use the configured defaultMessages sent from your phone starting with / are intercepted by the hub:
| Command | Description |
|---|---|
/h or /help | Show help |
/s or /sessions | List open sessions (Claude and terminal) |
/N or /N name | Switch to session N (optionally rename) |
/n or /new | Create a new Claude session |
/c | Clear context and resume (/clear + go) |
/ss or /screenshot | Capture active session's iTerm2 window |
/cc | Send Ctrl+C (interrupt) |
/esc | Send Escape |
/enter | Send Enter/Return |
/tab | Send Tab (trigger completion) |
/up /down /left /right | Arrow keys |
/p | Pause session |
/pick N [text] | Select menu option N, optionally type text |
/restart | Restart the watcher |
Send raw keystrokes to the active iTerm2 session from your phone:
| Command | Keystroke | Use case |
|---|---|---|
/cc | Ctrl+C | Interrupt a running process |
/esc | Escape | Dismiss a dialog, exit a mode |
/enter | Return | Confirm a prompt |
/tab | Tab | Trigger shell completion |
/up | Up arrow | Previous history / menu up |
/down | Down arrow | Next history / menu down |
/pick N | Down x (N-1) + Enter | Select the Nth option in a menu |
To get the most out of Telex, add these rules to your CLAUDE.md (or ~/.claude/CLAUDE.md for global config):
Tell Claude to send the same content it prints on the terminal to Telegram, so you can follow along from your phone:
Every response you give on the terminal MUST also be sent to Telegram via telegram_send.
Send the same content - do not shorten or paraphrase.
Adapt markdown for Telegram: use **bold** and *italic* only. No headers, no code blocks.
If Claude is about to spawn agents, read multiple files, or do anything that takes more than a few seconds, it should send a brief Telegram message first - before calling any other tools. Otherwise your phone goes silent and you don't know if Claude heard you.
If a task will take more than a few seconds, your FIRST tool call must be
telegram_send with a brief acknowledgment (e.g. "On it - researching that now.").
Then proceed with the actual work. Never leave Telegram silent while working.
Messages you send from your phone while Claude is generating a response may be queued. Call telegram_receive early in each session to catch them:
At the start of every session, call telegram_receive to drain any queued
messages that arrived while you were offline.
| Variable | Default | Description |
|---|---|---|
TELEGRAM_API_ID | (required) | Telegram API ID from my.telegram.org |
TELEGRAM_API_HASH | (required) | Telegram API hash from my.telegram.org |
TELEX_TTS_VOICE | bm_fable | Default TTS voice |
Environment variables can also be placed in ~/.aibroker/env for the launchd daemon to pick up automatically.
Telex runs as a macOS launchd agent (com.telex.watcher) that starts automatically and restarts if it crashes. It requires the AIBroker hub daemon (com.aibroker.daemon) to be running first.
node dist/index.js watch
telex service start # Install and start as launchd agent
telex service stop # Stop and unload
telex service status # Show running state
The agent uses KeepAlive: true and ProcessType: Interactive. The Interactive process type and LimitLoadToSessionType: Aqua are required so the adapter can access the macOS GUI session and call AppleScript to control iTerm2.
telex service (a wrapper for scripts/watcher-ctl.sh, which git checkouts can run directly) detects Linux and manages a systemd user unit (telex-watcher.service) instead of launchd. No sudo is used.
Prerequisites: Node.js 18+, systemd with a user session (systemctl --user works), the AIBroker hub running, and Telegram credentials in ~/.telex/credentials or the environment.
npm install -g @tekmidian/telex
telex service start # write ~/.config/systemd/user/telex-watcher.service, enable --now
telex service status
telex service stop # disable --now and remove the unit
telex service unit # write the unit only, do not start it
The unit runs with UMask=0077 and Restart=on-failure. It captures PATH and every AIBROKER_* / TELEX_* variable from the shell that runs start, plus the Telegram credentials. Output goes to ~/.local/state/telex/watch.log (0600, in a 0700 directory); journalctl --user -u telex-watcher shows unit events.
By default a user service stops when you log out. To keep the watcher running, enable linger once: loginctl enable-linger $USER (status and start print this hint when linger is off). The /ss screenshot command needs macOS and iTerm2 and replies that it is unsupported on Linux.
Telex no longer ships its own MCP server. The AIBroker unified MCP server provides all telegram_* tools. Add AIBroker to ~/.claude.json:
{
"mcpServers": {
"aibroker": {
"command": "node",
"args": ["/path/to/AIBroker/dist/mcp/index.js"]
}
}
}
See the AIBroker repo for full MCP setup instructions.
"Hub not running" or connection refused errors
The AIBroker daemon is not running. Start it first - Telex cannot function without it.
"Adapter not connected" errors
The Telex adapter is not running or has not registered with the hub. Start it with node dist/index.js watch or use telex service start.
Telegram authentication failed
Ensure TELEGRAM_API_ID and TELEGRAM_API_HASH are set. Run telegram_login from Claude or re-run setup.
Messages not appearing in Claude
Check that both AIBroker and Telex are running. Verify the session ID matches your Claude tab. Use telegram_status to confirm the adapter is connected.
"iTerm2 wants to control..." security prompt
Click OK. If you clicked "Don't Allow", go to System Settings > Privacy & Security > Automation and enable iTerm2.
TTS fails with "ffmpeg not found"
Install ffmpeg: brew install ffmpeg.
First TTS call takes a long time
The Kokoro model (~160 MB) is downloaded on first use and cached locally. Subsequent calls are fast.
~/.telex/. Treat them like passwords - they grant full access to your Telegram session.node dist/index.js uninstall
Or with npx from the published package:
npx -y @tekmidian/telex uninstall
This removes Telex from ~/.claude.json and deletes credentials from ~/.telex/auth/. To fully clean up:
telex service stoprm ~/Library/LaunchAgents/com.telex.watcher.plist (filename may vary - check scripts/watcher-ctl.sh in the package for the exact name)~/.telex/ entirely: rm -r ~/.telex/Restart Claude Code to apply.
MIT - see LICENSE
Matthias Nott - github.com/mnott
FAQs
Telegram MCP bridge for Claude Code — bidirectional self-chat via MTProto
The npm package @tekmidian/telex receives a total of 0 weekly downloads. As such, @tekmidian/telex popularity was classified as not popular.
We found that @tekmidian/telex demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Threat Research
/Security News
Socket uncovered secret-stealing workflows that ran in LiteLLM’s GitHub repository 11 days before the supply chain attack on PyPI and Docker.
Security News
Cloudflare introduces tsrs, a Rust port of TypeScript’s compiler promising faster checks and lower memory use, with the TypeScript team’s help.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.