Skip to main content
Glama
telegram-commandcode

telegram-commandcode

by qrak

telegram-commandcode

Telegram for your coding agent. An MCP server that lets Claude Code, Cursor, Codex CLI, Command Code or any other MCP client send you messages, files, photos and progress updates — and read your replies back.

CI License: MIT Node

   your agent ──MCP stdio──▶ telegram-commandcode ──HTTPS──▶ Telegram ──▶ your phone
        ▲                                                                     │
        └────────────────────── reply via getUpdates ◀───────────────────────┘

The repository contains three independent pieces:

Piece

Direction

Language

What it does

MCP server (index.js)

agent → Telegram

Node

Seven tools: send message / photo / file, read updates, react, download, health check

Bot daemon (telegram_commandcode/)

Telegram → agent

Python

48 commands, streaming output, persistent sessions; frozen at 2.2.0 (see status below)

ACP bridge (acp-bridge/)

Telegram → agent

Node

Drives any ACP agent: sessions, streaming, approvals, /compact, /resume

You can use any of them alone. The MCP server is the part that works with every agent; the daemon is specific to the Command Code CLI — and not needed at all if you already use Command Code's own /rc; the ACP bridge is the portable chat driver for agents that speak ACP.

Command Code ships this itself now

If you use Command Code and just want it on your phone, the daemon below is redundant: since Remote Control (announced 2026-09-29) an open session can be driven from Telegram or Discord with /rc.

Command Code /rc

MCP server (this repo)

Bot daemon (this repo)

Direction

live session ↔ chat

any agent → chat, replies back

chat drives a CLI

Works with

Command Code only

any MCP client

Command Code only

Needs an open session

yes

no

no

Status: the MCP server is the maintained part. The daemon is frozen at 2.2.0 — correct and tested, still useful for self-hosting a bot on a server or driving a CLI from a chat, but it gets no new features.

The MCP server is the part /rc does not replace: it works with every agent, it can notify you from a CI job or a short-lived agent that has no session to keep open, and it reads your replies back.

Quick start — MCP server

You need a bot token from @BotFather and your numeric chat id (send the bot a message, then read chat.id from https://api.telegram.org/bot<TOKEN>/getUpdates).

Command Code

cmd mcp add telegram \
  -e TELEGRAM_BOT_TOKEN=<token> \
  -e TELEGRAM_DEFAULT_CHAT_ID=<chat_id> \
  -- npx -y github:qrak/telegram-commandcode

Claude Code

claude mcp add telegram \
  -e TELEGRAM_BOT_TOKEN=<token> \
  -e TELEGRAM_DEFAULT_CHAT_ID=<chat_id> \
  -- npx -y github:qrak/telegram-commandcode

Cursor / other MCP clients

Add a stdio server with the command npx and arguments ["-y", "github:qrak/telegram-commandcode"], plus the two environment variables above (~/.cursor/mcp.json for Cursor).

Restart the agent, then ask it to call telegram_health. You should get your bot's username back.

What the agent can do

Tool

Purpose

telegram_send_message

Text, plain or formatted; 4096-char limit enforced with a clear error

telegram_send_photo

Local path or URL, up to 10 MB

telegram_send_file

Any document up to 50 MB — logs, diffs, PDFs, zips

telegram_get_updates

Read replies; only unseen messages by default

telegram_send_reaction

👀 / ✅ / ❌ on a message

telegram_download_file

Pull a file the user sent, up to 20 MB

telegram_health

Verify the token before doing anything else

The server retries 429/5xx with backoff, retries once without parse_mode when Telegram rejects the markup, redacts the token from every error it returns, and refuses to start silently without a token — it exposes a single telegram_status tool that explains the setup instead.

Related MCP server: mcp-telegram

Quick start — bot daemon (Command Code only)

git clone https://github.com/qrak/telegram-commandcode.git
cd telegram-commandcode
python -m venv .venv && . .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -e .
export TELEGRAM_BOT_TOKEN="123456:ABC..."
export TELEGRAM_ALLOWED_USERS="<your numeric user id>"
export COMMAND_CODE_WORKDIR="$HOME/projects/my-app"
telegram-commandcode

Then message the bot: a plain message becomes a prompt for cmd, and slash commands map to the CLI — /model, /plan, /review, /status, /stop and 43 more. Type / in Telegram to see the menu.

Sessions, compaction and forks

The daemon keeps one Command Code session per chat and captures its id from each run (--output-format json), so the session history is not guesswork:

You want

Command

What actually happens

Continue where you left off

/resume

--continue on the next prompt

Attach to a named/known session

/resume <name|id>

--resume <name> on the next prompt

Name the current session

/rename <name>

later runs pass -n <name>

Branch off

/fork [name]

next prompt runs --continue --fork-session -n <name>; the original transcript is untouched

Shrink the context

/compact

one read-only summarisation run builds a handoff brief, then a new session is seeded with it

Step back N turns

/undo [N]

same brief, describing the state before the last N prompts; those prompts drop out of the history

Wipe everything

/clear

new session, no brief

/compact and /undo make one extra model call; if it fails, nothing is changed and the bot says so. The handoff brief is injected exactly once, so it does not keep costing tokens on every later turn.

Other settings are passed per run rather than written and forgotten: /model → -m, /effort → --effort, /compact-mode → --config compact-mode=<default|fast> (also persisted as compactMode). /usage and /context report the real token counts each run reports back.

Configuration

Variable

Default

Meaning

TELEGRAM_BOT_TOKEN

—

Required. From @BotFather

TELEGRAM_ALLOWED_USERS

(empty = locked)

Comma-separated numeric ids, or any to opt in to open access

COMMAND_CODE_CMD

cmd

Path to the Command Code binary

COMMAND_CODE_WORKDIR

current directory

Where the agent runs

COMMAND_CODE_YOLO

true

false runs the agent without --yolo

COMMAND_CODE_TRUST

true

false omits --trust (project trust prompt)

COMMAND_CODE_JSON

true

false drops --output-format json on older CLI builds; also loses session ids and token counts

COMMAND_CODE_MAX_TURNS

20

Max turns per prompt

OPENAI_API_KEY

—

Optional, enables voice transcription

An empty allow-list is fail-closed: the bot replies with your numeric id and instructions instead of executing anything. TELEGRAM_ALLOWED_USERS=any is an explicit opt-in, not the default.

Run it as a service

cp deploy/telegram-commandcode.service ~/.config/systemd/user/
# edit ExecStart / EnvironmentFile / WorkingDirectory first
systemctl --user daemon-reload
systemctl --user enable --now telegram-commandcode.service

ACP bridge — Telegram ↔ any ACP agent

acp-bridge/ is a single-file Node client for the Agent Client Protocol. It spawns the agent over stdio, keeps one ACP session per chat and turns protocol events into chat UI: session/update streams into one edited message, session/request_permission becomes inline buttons, /compact and /resume are implemented on top of session/prompt, session/list and session/resume.

cd acp-bridge && npm install
cp agents.example.json agents.json   # token, chatId, cwd, agents
npm start

Command

What it does

/agent

list agents, /agent <name> switches

/new

new session, drops the context

/resume

list stored sessions, /resume <n|id> attaches one

/compact

agent writes a handoff brief, a new session continues from it

/status

agent, session, busy state, capabilities

/cancel

session/cancel for the running turn

Full details, config schema and limitations: acp-bridge/README.md.

Status

Tested end to end against DeepSeek Harness (dsh --profile acp, ACP v1): sessions, streaming, cancel, session/list/session/resume, /compact, permission buttons.

Missing and planned

Agent

Adapter

State

Next step

DeepSeek Harness

native (dsh acp)

✅ working

command/mode discovery once upstream advertises it

Claude Code

@zed-industries/claude-code-acp

⏳ wired, untested

install CLI + log in, then run the smoke test

Codex

@zed-industries/codex-acp

⏳ wired, untested

same, with codex login / OPENAI_API_KEY

Gemini CLI

--experimental-acp

⏳ wired, untested

confirm the flag per version, add to CI

Not implemented yet:

  • Slash-command discovery. The bridge logs available_commands_update when an agent sends it, but DSH sends none, so the agents' own commands (/plan, /model, /goal) never reach the Telegram menu.

  • Model and mode switching. session/set_config_option / session/set_mode are unsupported by the current DSH build (modes: null, no config options); DSH's private providers/list + providers/set are a possible shortcut.

  • Media. Text only; image/audio forwarding depends on promptCapabilities, which DSH advertises as empty.

  • Real compaction. /compact is a summarise-then-restart with a handoff brief, not the agent's internal compaction plugin.

  • Queueing. One turn per chat; a second message while busy is rejected.

Planned, roughly in order: per-adapter smoke test (so "supported" means "checked"), command menu from available_commands_update, model/mode switching, media, per-chat queue.

Security

This tool gives a chat app the ability to drive an agent that edits files and runs shell commands. Read SECURITY.md before exposing it:

  • set TELEGRAM_ALLOWED_USERS to your own id,

  • run it in a project directory, not your home directory,

  • treat the bot token like an SSH key,

  • on a shared host, run the bot in a container under a dedicated user.

COMMAND_CODE_YOLO=true is the intended mode — and it is remote code execution by design. Do not put production credentials on the host.

Requirements

  • MCP server: Node.js ≥ 18, a Telegram bot token.

  • Bot daemon: Python ≥ 3.11, python-telegram-bot 20–21, the Command Code CLI on PATH. Command Code is closed-source and requires its own subscription; the bot daemon is only useful if you already use it.

Development

npm install
npm test                       # 6 MCP protocol tests (spawns the real server)
npm run deadcode               # knip: unused JS files, exports, dependencies

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest                         # 163 unit tests, no network, no `cmd` needed
python -m vulture              # dead Python code (clean; see docs/dead-code-audit.md)

CI runs both test suites on Linux and Windows.

Repository layout

index.js                     MCP server (the agent-facing part)
package.json                 npm metadata, tests, bin
acp-bridge/                  Telegram ↔ any ACP agent (standalone Node app)
  acp-bridge.mjs             the whole bridge: ACP client + Telegram UI
  agents.example.json        per-agent command lines (copy to agents.json)
telegram_commandcode/        Python bot daemon
  gateway/                   router, sender, processor, media
  commands/                  slash-command handlers (48)
  executor.py                async `cmd` subprocess runner
  formatter.py, chunking.py  MarkdownV2 escaping and 4096-char splitting
skill/                       publishable SKILL.md + references for agent
                             marketplaces (Agensi, Claude Code skills)
tests/                       pytest suite
test/                        MCP protocol tests (node:test)
legacy/                      original Node bot, archived and unsupported
deploy/                      systemd unit

Publishing as an agent skill

skill/ is a self-contained SKILL.md package: the playbook for when and how an agent should use these tools, including MarkdownV2 pitfalls, limits, approval loops and troubleshooting. Build the upload zip with:

node scripts/build-skill.mjs     # writes dist/telegram-bridge-skill.zip

The skill depends on this repository (MIT) but is not a copy of it: it encodes the operating knowledge, while the MCP server stays free here.

Status and known limits

  • The MCP server is tested against @modelcontextprotocol/sdk 1.29 and Node 18/20/22.

  • The ACP bridge is tested only against DeepSeek Harness. The Claude Code, Codex and Gemini adapters are configured in agents.example.json but have not been run against real installations — treat them as unverified.

  • The ACP bridge implements /compact itself (handoff brief + new session); it is not the agent's internal compaction.

  • The bot daemon calls the cmd CLI with -p <prompt> and Command Code flags; it is coupled to that CLI's argument surface by definition.

  • Command Code is not open source, so the daemon cannot be tested end-to-end in CI. Everything that does not need the binary is unit-tested.

  • telegram_get_updates acknowledges updates: do not run the bot daemon, the ACP bridge and the MCP server's read path against the same token at the same time, or they will steal each other's messages.

License

MIT — see LICENSE.

Available Tools

7 tools
telegram_download_fileA

Download a file from Telegram by file_id (max 20 MB via the Bot API) and return its local path.

Inputs: file_id (required).

telegram_get_updatesA
Read-only

Fetch recent incoming messages. By default only unseen updates are returned and acknowledged; pass offset: 0 to re-read the backlog.

Inputs: limit, offset, timeout.

telegram_healthA
Read-only

Check that the bot token works: returns bot id, username and capabilities.

Inputs: no named parameters.

telegram_send_fileA

Send a document/file via an absolute local path or public URL (max 50 MB). Useful for build logs, diffs, screenshots and reports.

Inputs: file_path (required), caption, chat_id, parse_mode.

telegram_send_messageA

Send a text message to a Telegram chat. Supports MarkdownV2 and HTML parse modes. Messages longer than 4096 characters are rejected by Telegram — split them first.

Inputs: text (required), chat_id, parse_mode.

telegram_send_photoA

Send a photo via a public URL or an absolute local file path (max 10 MB for photos).

Inputs: photo (required), caption, chat_id, parse_mode.

telegram_send_reactionA

Set an emoji reaction on a message (👀 working, ✅ done, ❌ failed). The bot must be a member of the chat.

Inputs: emoji (required), message_id (required), chat_id.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct action: three send variants are cleanly separated by payload type (text, photo, document) with explicit size limits, and get_updates/download_file/reaction/health have no overlap. An agent can pick the right tool from the names alone.

    Naming Consistency4/5

    All tools share a consistent `telegram_` prefix and snake_case, with verb_noun forms for the action tools (send_message, get_updates, download_file). The only deviation is `telegram_health`, a noun phrase rather than a verb, but it remains readable and predictable.

    Tool Count5/5

    Seven tools is well-scoped for a Telegram bot bridge: send, receive, download, react, and health-check. Nothing feels redundant or missing from a count perspective.

    Completeness4/5

    Core lifecycle is covered: outbound text/media, inbound updates, file download, reactions, and auth verification. Gaps exist around message management (edit, delete, reply/thread targeting) and chat introspection (list chats, get chat info), which agents may need for richer interactions.

    Related MCP Connectors

    Related MCP Servers

    • 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.
      5
      8
      -
    • A
      license
      B
      quality
      D
      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.
      100
      455 npm
      34
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server enabling AI agents to interact with users via Telegram, supporting message and image sending, inline quick replies, and waiting for user responses.
      5 npm
      MIT