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, with access to shared git repositories.

Features

Isolated sessions

Each user gets their own Claude Code subprocess. Sessions are isolated — your work is private to you.

Shared repositories

Repos are cloned once to a central directory. Multiple users access the same clone without duplicating storage.

Project-level agents

Claude runs at the project root, auto-discovering agents and skills defined in .claude/agents/.

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