telegram-sessions
WARNING: Sessions spawned from Telegram run with --dangerously-skip-permissions, which means Claude can execute any command without confirmation. Use at your own risk. Only allow access to trusted users and always lock down access policy to allowlist after setup.
Telegram channel for Claude Code. Run multiple Claude sessions, manage them from Telegram with /new, /sessions, /kill.
Prerequisites
Install
git clone https://github.com/Bergamolt/telegram-sessions.git
cd telegram-sessions
bun install
Add the plugin to Claude Code:
# Add the local marketplace
/plugin marketplace add /path/to/telegram-sessions
# Install the plugin
/plugin install telegram-sessions@telegram-sessions-marketplace
# Reload to activate
/reload-plugins
The plugin registers its MCP server and skills automatically.
Setup
Everything is done through built-in skills — no need to edit config files manually.
1. Save your bot token
/telegram-sessions:configure <your-bot-token>
The token is stored in ~/.claude/channels/telegram-sessions/.env.
2. Check status
/telegram-sessions:configure
Shows: token status, access policy, allowed users, pending pairings, and next steps.
3. Pair your Telegram account
DM your bot on Telegram. It replies with a 6-character pairing code. Approve it:
/telegram-sessions:access pair <code>
4. Lock down access
Once everyone who needs access has paired, switch from pairing mode to allowlist:
/telegram-sessions:access policy allowlist
Now only approved users can reach Claude through the bot.
Usage from Telegram
| Command | Description |
|---|
/new [name] [--skip-permissions] [--continue] | Start a new Claude session (runs in tmux) |
/sessions | List active sessions with inline buttons to switch |
/session | Info about current session |
/last | Show the last reply from the current session |
/kill <name> | Kill a session |
/projects | List saved projects |
/projects add <name> <path> | Save a project (used as cwd for /new <name>) |
/projects remove <name> | Remove a saved project |
/restart | Restart the daemon |
/status | Check your pairing state |
/help | List available commands |
/start | Pairing instructions |
Regular messages are routed to the active session. Text, photos, documents, voice messages, and audio files are forwarded. Claude replies directly in the chat with markdown formatting.
Permissions
When a session requires tool approval (running without --skip-permissions), the bot sends an interactive message with See more / Allow / Deny buttons. "See more" expands the full tool details with pretty-printed input. Only allowlisted users can approve permissions. The verdict is forwarded back to the Claude session in real time.
File attachments
Photos are downloaded eagerly on arrival and the local path is included in the notification. Documents, voice messages, and audio files include attachment_file_id in the metadata — use the download_attachment tool to fetch them to the local inbox (Telegram caps bot downloads at 20MB).
Voice transcription
Configure a shell command to automatically transcribe voice and audio messages. When set, Claude will download the file and run the command to get the transcript.
/telegram-sessions:access set transcribe whisper --model base --output_format txt --output_dir -
The command receives the file path as the last argument and should output the transcript to stdout. Any tool that follows this contract works — OpenAI Whisper, a custom script, etc.
To disable:
/telegram-sessions:access set transcribe ""
Access management
/telegram-sessions:access # show status
/telegram-sessions:access pair <code> # approve a pairing
/telegram-sessions:access deny <code> # reject a pairing
/telegram-sessions:access allow <senderId> # add user by ID
/telegram-sessions:access remove <senderId> # remove user
/telegram-sessions:access policy <mode> # pairing | allowlist | disabled
/telegram-sessions:access group add <groupId> # allow a group chat
/telegram-sessions:access group rm <groupId> # remove a group chat
/telegram-sessions:access set ackReaction <emoji> # reaction on received messages
/telegram-sessions:access set replyToMode <mode> # off | first | all
CLI wrapper
The plugin includes bin/claude-telegram for launching sessions from the terminal:
claude-telegram --name my-session
claude-telegram --name my-session --skip-permissions
claude-telegram --help
To make it available globally:
