Skip to main content
Glama
telegram-commandcode

telegram-commandcode

by qrak
README.md
# 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](https://github.com/qrak/telegram-commandcode/actions/workflows/ci.yml/badge.svg)](https://github.com/qrak/telegram-commandcode/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)

```
   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](https://agentclientprotocol.com) 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](https://commandcode.ai/docs/remote-control) (announced
[2026-09-29](https://commandcode.ai/blog/remote-control-now-available-in-command-code))
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](https://t.me/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

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

### Claude Code

```bash
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.

## Quick start — bot daemon (Command Code only)

```bash
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 .
```

```bash
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

```bash
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](https://agentclientprotocol.com). 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`.

```bash
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`](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](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

```bash
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:

```bash
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](LICENSE).

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.