Skip to main content
Glama
qrak

telegram-commandcode

by qrak
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

telegram-commandcode v2

Async Python Telegram bot for Command Code CLI — Hermes Agent architecture patterns.

Control your AI coding agent from Telegram with streaming progress, persistent sessions, and resilient message delivery. Rewritten in Python with python-telegram-bot 20.x.

           Telegram
               ↕
    ┌──────────┴──────────┐
    │  bot.py (gateway)   │  Async Python PTB bot
    │  index.js (MCP)     │  Node.js MCP server (unchanged)
    └──────────┬──────────┘
               ↕
        command code CLI

Two Modes

Mode

File

Language

Direction

Purpose

Bot Daemon

telegram_commandcode/bot.py

Python

Telegram → CC

Async gateway with streaming progress

MCP Server

index.js

Node.js

CC → Telegram

Agent sends messages, files, photos

Related MCP server: Telegram MCP Server

Architecture (v2)

telegram_commandcode/
├── bot.py         # PTB Application — entry point & lifecycle
├── gateway.py     # Async event router — non-blocking dispatch
├── commands.py    # 46+ slash command handlers
├── executor.py    # Async subprocess runner for `cmd`
├── session.py     # Persistent session state (JSON-backed)
├── formatter.py   # MarkdownV2 escaping & safe formatting
├── chunking.py    # Smart 4096-char split + file fallback
└── __init__.py

Key Architectural Patterns

Pattern

Implementation

Decoupled Gateway

PTB message handler is thin — never blocks. Long work dispatched via asyncio.create_task() in per-chat asyncio.Lock

Persistent Sessions

ChatSession dataclass stored in ~/.commandcode/telegram_sessions.json. Survives restarts

Streaming Progress

Edit-in-place: one status message, progressively edited with stages (🤔→✅/❌). No message flooding

Resilient Chunking

SmartSplitter: splits at paragraph → sentence → word boundaries, capped at 4000 chars. File fallback at 15K chars

Error Boundaries

Every send_message/edit_message_text wrapped with parse-fallback. Reactions are best-effort

Quick Install

# Clone and install
git clone https://github.com/qrak/telegram-commandcode.git
cd telegram-commandcode
pip install -e "."

# Or with voice transcription support
pip install -e ".[voice]"

Requirements

  • Python 3.11+

  • python-telegram-bot[job-queue]>=20.8

  • Command Code CLI (cmd) installed and on PATH

  • (Optional) openai for voice transcription

Setup

# 1. Get bot token from @BotFather
# 2. Set environment variables
export TELEGRAM_BOT_TOKEN="123456:ABC..."
export TELEGRAM_ALLOWED_USERS="any"  # or comma-separated user IDs

# 3. Start the bot
telegram-commandcode
# or: python -m telegram_commandcode.bot

Env Vars

Variable

Default

Description

TELEGRAM_BOT_TOKEN

(required)

Bot token from @BotFather

TELEGRAM_ALLOWED_USERS

any

Comma-separated user IDs

COMMAND_CODE_CMD

cmd

Path to Command Code binary

COMMAND_CODE_YOLO

true

false → read-only mode

COMMAND_CODE_MAX_TURNS

20

Max conversation turns per prompt

OPENAI_API_KEY

(optional)

For voice message transcription

systemd Service (persistent)

# ~/.config/systemd/user/telegram-commandcode.service
[Unit]
Description=Telegram Command Code Bot
After=network-online.target

[Service]
Type=simple
ExecStart=/home/user/.local/bin/telegram-commandcode
Environment="TELEGRAM_BOT_TOKEN=your_token"
Environment="COMMAND_CODE_YOLO=true"
Restart=always
RestartSec=5

[Install]
WantedBy=default.target
systemctl --user daemon-reload
systemctl --user enable --now telegram-commandcode.service

Features

Feature

Description

👀 Reactions

👀 while processing, ✅ on success, ❌ on error

📷 Photo reception

Photos downloaded and passed to cmd

📄 File reception

Documents sent to /tmp/telegram-cmd/

🎤 Voice transcription

OpenAI Whisper (requires OPENAI_API_KEY)

📎 Auto-send files

MEDIA:/path in output → auto-attached

👥 Group chat

Responds when @mentioned or replied to

✏️ Single-message editing

Status message edited in-place — no chat clutter

🔄 Session chaining

/resume reads CC session history

🎯 Goal tracking

/goal <text> sets standing objective

🧭 Mid-session steering

/steer <text> guides all subsequent prompts

📋 Prompt queueing

/queue <prompt> queues for next turn

🔄 Background tasks

/background <prompt> runs detached

⚙️ Config persistence

Model/provider/effort persist to ~/.commandcode/config.json

Slash Commands

All 46+ commands from the Node.js version are implemented. Type / in Telegram to see the menu.

CLI-mapped: /feedback, /learntaste, /login, /logout, /mcp, /skills, /taste, /info, /version, /update

Config & session: /status, /model, /effort, /provider, /add-dir, /goal, /steer, /plan, /compact-mode, /configure-models, /context

Session control: /resume, /clear, /new, /fork, /rename, /undo, /retry, /queue, /background, /stop, /reload

Prompt-based: /review, /init, /memory, /pr-comments, /agents, /cmd

MCP Server (unchanged)

The Node.js MCP server (index.js) remains for Command Code → Telegram direction:

cmd mcp add telegram \
  -e TELEGRAM_BOT_TOKEN=*** \
  -e TELEGRAM_DEFAULT_CHAT_ID=1141080547 \
  -- npx github:qrak/telegram-commandcode

License

MIT

This server cannot be installed

A
license - permissive license
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • telegram-mcp

    zhigang1992
    A
    license
    -
    quality
    C
    maintenance
    An MCP server that enables interaction with Telegram to send, read, and search messages across chats and dialogs. It supports waiting for incoming messages and retrieving conversation history through natural language commands.
    Last updated
    35
    4
    MIT

  • Telegram MCP Server

    BrainDAO
    F
    license
    A
    quality
    D
    maintenance
    An MCP server for interacting with Telegram bots and channels using the Telegraf library. It allows AI agents to send messages, manage channels, forward content, and intelligently respond to Telegram conversations.
    Last updated
    5
    69
    8

  • mcp-telegram

    beautyfree
    A
    license
    B
    quality
    B
    maintenance
    A Telegram MCP server that connects agents to a real Telegram user account via MTProto, enabling reading, searching, sending, moderating, and managing Telegram chats through natural language or automated tool calls.
    Last updated
    100
    91
    28
    MIT

View all related MCP servers

Related MCP Connectors

  • telegram-mcp

    Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.

  • gainium-mcp

    MCP server for Gainium — manage trading bots, deals, and balances via AI assistants

  • microservices.sh

    MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/qrak/telegram-commandcode'

If you have feedback or need assistance with the MCP directory API, please join our Discord server