Introduction

tg-claude-bridge lets you use Claude Code from any Telegram client — mobile or desktop. Send messages to a bot, and Claude Code runs in an isolated session per user, inside a workspace of git repositories you control.

Features

Isolated sessions

Each user gets a persistent workspace directory. Sessions are isolated — your work is private to you.

Multi-repo workspaces

Clone any number of repositories into your workspace. Switch between them without losing context.

Git branch support

List, switch, and create branches directly from Telegram. Claude runs inside the correct branch.

Custom slash commands

Define reusable prompts as slash commands in commands.json. Supports {{args}} substitution.

MCP tool support

Claude can invoke MCP tools that send messages and documents back to your Telegram chat.

Auto-cleanup

Sessions end automatically after 10 minutes of inactivity to free resources.

How it works

Telegram DM  →  Telegraf bot  →  SessionManager  →  ClaudeSession (CLI subprocess)
                                                                  ↓
                                                    MCP Server (stdio)
                                                                  ↓
                                               RelayServer (HTTP)  →  Telegram

1. A message arrives via Telegram long-polling
2. SessionManager forwards it to an isolated Claude Code subprocess
3. Claude invokes MCP tools; the MCP server proxies back via a local relay
4. Responses are sent back to Telegram via a serial message queue