telegram-sessions-marketplace

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

• Claude Code CLI
• Bun runtime
• Telegram bot token from @BotFather

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: