claude-code-telegrammer

Custom Telegram MCP server + TUI auto-responder for running Claude Code as an autonomous Telegram agent

Documentation · pip install claude-code-telegrammer

What it is: a self-contained Telegram bridge for Claude Code — a Bun MCP server that turns any Claude Code session into an autonomous agent you talk to over Telegram, plus a TUI watchdog that keeps it running unattended. Each agent runs its own bot, its own message store, and fails loud on misconfiguration.

Problem and Solution

_{Table 1. Eight issues with the official Telegram plugin (as of April 2026) and how claude-code-telegrammer addresses each.}

Quickstart

Prerequisites: Bun ≥ 1.0 (MCP server); GNU Screen (watchdog, optional).

git clone https://github.com/ywatanabe1989/claude-code-telegrammer.git
cd claude-code-telegrammer/ts && bun install

1. Get a bot token — message @BotFather, send /newbot, and copy the token (123456789:AAH...). Open your bot and send it any message. Verify: curl -s "https://api.telegram.org/bot<TOKEN>/getMe".

2. Register the MCP server with Claude Code — copy .mcp.json.example to .mcp.json (gitignored) and set CLAUDE_CODE_TELEGRAMMER_BOT_TOKEN + CLAUDE_CODE_TELEGRAMMER_ALLOWED_USERS (your Telegram user id, from @userinfobot). Full env reference: docs/configuration.md.

3. Run:

claude --dangerously-skip-permissions \
       --dangerously-load-development-channels server:claude-code-telegrammer

You should see Listening for channel messages from: server:claude-code-telegrammer. Message your bot from Telegram — Claude Code receives it as a channel notification.

Architecture

flowchart LR
    op["Operator<br/>(Telegram app)"]
    bot["Telegram Bot API<br/>per-agent bot token"]
    op <-->|messages| bot

    subgraph agent["One agent — isolated home"]
        direction TB
        srv["telegram-server.ts<br/>(Bun MCP server)"]
        gate{"allowlist gate<br/>CCT_ALLOWED_USERS<br/>+ access.json"}
        db[("state dir · per-agent<br/>messages.db · lock<br/>CCT_AGENT_STATE_DIR")]
        cc["Claude Code<br/>(the agent)"]
        srv -->|inbound| gate
        gate -->|"allowed → channel notification"| cc
        cc -->|"reply · react · send_document (MCP stdio)"| srv
        srv <--> db
    end

    bot -->|"getUpdates (long-poll)"| srv
    srv -->|sendMessage| bot

The MCP server long-polls Telegram, gates inbound messages through the allowlist, and delivers them to Claude Code as channel notifications; the agent replies through MCP tools. Each agent is self-contained — its own bot token, its own per-agent state dir, its own poller — and fails loud at startup on any misconfiguration (missing/invalid token, unexpanded ${…}, or a renamed env var). Deep dive: docs/architecture.md.

Interfaces

• MCP server — 11 tools over stdio (reply, react, edit_message, get_history, get_unread, mark_read, download_attachment, send_document, search_messages, get_context, health) with a built-in responsiveness policy. See docs/interfaces.md.
• config probe — bun run ts/telegram-server.ts config [--check] prints the resolved config as JSON for orchestrator preflight.
• health (doctor) — bun run ts/telegram-server.ts health (also exposed as the health MCP tool) runs 10 checks — env hygiene, token presence/validity, webhook absence, poller liveness, allowlist, state dir, DB schema/offset — and prints {package, ok, checks[], summary}; every failing check carries an actionable hint. See docs/interfaces.md.
• Skill — bundled at src/claude_code_telegrammer/_skills/claude-code-telegrammer/SKILL.md.

Part of SciTeX

claude-code-telegrammer is part of SciTeX — the Telegram communication layer and TUI watchdog used by scitex-agent-container (lifecycle, health, restart) and scitex-orochi (agent definitions, dashboard) for autonomous agent operation. See the agent stack.

References

• Claude Code Channels -- Claude Code's channel system
• Official Telegram Plugin -- the plugin:telegram@claude-plugins-official source
• #851 · #1075 · #1146 -- the upstream issues this project fixes
• Telegram BotFather · Telegram Bot API · MCP Specification
• Issues · Pull Requests

Four Freedoms for Research

0. The freedom to run your research anywhere -- your machine, your terms.
1. The freedom to study how every step works -- from raw data to final manuscript.
2. The freedom to redistribute your workflows, not just your papers.
3. The freedom to modify any module and share improvements with the community.

AGPL-3.0 -- because we believe research infrastructure deserves the same freedoms as the software it runs on.