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.

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