Telegram Plugin: Architecture & Data Flow

⏱ Est. reading time: 3 min Updated on 5/7/2026

The Telegram plugin architecture is decentralized compared to the official bridge.

Component Architecture

flowchart LR
  subgraph Cloud[Telegram Cloud]
    BotAPI[Bot API]
  end
  subgraph Local[Local Machine]
    Server[Bun MCP Server]
    Access[(access.json)]
    Inbox[(inbox/*)]
    CLI[Claude Code CLI]
  end
  Phone[Telegram Client] <--> BotAPI
  Server <--Long Poll--> BotAPI
  Server --- Access
  Server --- Inbox
  Server <--MCP Channels--> CLI

Data Flows

  • Inbound: User sends message → Bot API → Local Server (long-poll) → Validation (access.json) → <channel> notification to CLI.
  • Outbound: Agent calls reply → Local Server → Bot API → Message arrives at Client.
  • File Handling: Images are automatically downloaded to ~/.claude/channels/telegram/inbox/ because Bot API doesn't allow fetching old images later.

Pairing State Machine

stateDiagram-v2
  [*] --> Stranger
  Stranger --> Pending: First DM in pairing mode
  Pending --> Allowed: /telegram:access pair 
  Allowed --> Allowed: Subsequent DMs pass
  Allowed --> [*]: /telegram:access remove

Related Tools & Resources

Related Products

📦

mempalace

MemPalace is a local-first AI memory tool designed to store conversation history verbatim and retrieve it through semantic search, without summarizing or paraphrasing. It utilizes a structured index, categorizing information into "wings," "rooms," and "drawers" to enable scoped searches. The retrieval layer is pluggable (ChromaDB by default), ensuring all data remains on the user's machine unless opted out. It achieves an impressive 96.6% R@5 raw recall on the LongMemEval benchmark, notably without requiring LLMs or API calls, showcasing high performance in a local environment.
📦

code-review-graph

code-review-graph is an AI-assisted code review tool that builds a structural map of code using Tree-sitter and incrementally tracks changes to provide precise context to AI assistants via the Model Context Protocol (MCP). This approach significantly reduces token consumption by enabling AI models to read only the minimal set of files relevant to a change, rather than the entire codebase. It aims to solve the token waste problem in large repositories and monorepos, improving the efficiency and quality of AI code reviews.
📦

claude-context

Claude Context is an MCP (Model Context Protocol) plugin developed by Zilliztech, designed to provide deep code context to Claude Code and other AI coding assistants. It leverages semantic search to efficiently retrieve relevant code snippets from entire codebases, injecting them directly into the AI's context. This approach addresses the limitations of context windows and high costs associated with large codebases by storing the codebase in a vector database for efficient management and cost-effectiveness.