telegram-topics

telegram-topics

A Claude Code channel plugin that routes each project to its own Telegram Forum Topic.

Unlike the official Telegram plugin — which funnels every Claude Code session into a single flat chat — telegram-topics creates one topic per project directory. Messages in each topic reach only the Claude Code instance running in the corresponding project. Replies, reactions, attachments, and permission prompts all route back to the correct topic.

Features

• One topic per project. /Users/amir/Development/my-api gets its own Forum Topic, separate from /Users/amir/Development/web-app.
• Same capabilities as the official Telegram plugin. Reply, react, download attachments, edit messages, permission relay, sender allowlists, pairing flow.
• Auto-managed daemon. A single long-lived process owns the bot and serves all local Claude Code sessions over a Unix socket. Auto-starts on first session, idles out after the last one disconnects.
• Concurrency-safe startup. Simultaneous Claude Code sessions can't spawn duplicate daemons — an atomic lifetime lock on daemon.lock guarantees exactly one daemon per state dir, so you never hit the 409 Conflict bot-token race. Shim-side withSpawnLock serializes spawn attempts on top of that.
• Parallel sessions in the same project. Two Claude Code sessions in the same directory each get their own topic automatically: the first gets the primary, the second gets ${basename} (#2), the third gets (#3), etc. Freed slots are reused. Set TELEGRAM_TOPICS_INSTANCE=<name> if you want a stable, human-chosen name instead of an integer.
• Remove topics safely. /telegram-topics:project remove <name> deletes a topic from Telegram and clears local state — guarded by a two-step token confirmation.
• Rename topics live. /telegram-topics:configure topic "<name>" renames the calling session's own topic immediately via editForumTopic — no session restart. Routed through the shim's rename_topic MCP tool so auto-suffixed sessions correctly rename their own topic (e.g. ${cwd}#2), not whichever session currently holds the primary slot. Add --instance <inst> to target a different slot (1 = primary, 2/3/… = integer slot, any other string = named instance).
• Self-healing across updates. When you /plugin update, the shim detects a stale daemon from the old cache path and restarts it.

How it works

┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ Claude Code  │  │ Claude Code  │  │ Claude Code  │
│  (my-api)    │  │  (web-app)   │  │  (cli-tool)  │
│   ┌──────┐   │  │   ┌──────┐   │  │   ┌──────┐   │
│   │ Shim │   │  │   │ Shim │   │  │   │ Shim │   │
│   └──┬───┘   │  │   └──┬───┘   │  │   └──┬───┘   │
└──────┼───────┘  └──────┼───────┘  └──────┼───────┘
       │    Unix socket  │                 │
       └────────┬────────┘─────────────────┘
                │
         ┌──────┴──────┐
         │   Daemon    │────── Telegram Bot API
         │  (grammy)   │       (getUpdates long poll)
         └──────┬──────┘
                │
    ┌───────────┴───────────┐
    │  Telegram Supergroup  │
    │  (Forum Topics on)    │
    ├───────────────────────┤
    │  my-api               │
    │  web-app              │
    │  cli-tool             │
    └───────────────────────┘

• Shim (shim.ts): small MCP server spawned by each Claude Code session. Registers its project directory with the daemon, relays tool calls and inbound messages.
• Daemon (daemon.ts): long-lived background process. Owns the bot, polls Telegram, manages topics, routes between topics and shims.
• State: everything lives under ~/.claude/channels/telegram-topics/.

Install

This plugin isn't on Anthropic's approved allowlist, so it runs under the development flag.

# Add the marketplace (one-time)
/plugin marketplace add wilfoa/claude-plugins

# Install
/plugin install telegram-topics@wilfoa-plugins
/reload-plugins

Setup

Setup has two phases:

• One-time setup (§1–5): create the bot, the supergroup, the chat ID, save them to Claude Code, pair your Telegram account. Do this exactly once per machine.
• Per-project setup (§6): cd into the project and run Claude Code with the channel flag. The topic is created on first connect. Optionally rename it.

One-time setup

1. Create a Telegram bot

Message @BotFather, run /newbot, pick a display name and a unique username ending in bot. Copy the token it returns.

Important: if you also run the official Telegram plugin, use a different bot token for telegram-topics. Telegram allows only one getUpdates poller per token; two daemons on the same token will throw 409 Conflict forever.

2. Create the supergroup with Topics enabled