telegram-commandcode: Instructions file for Codex

AGENTS.md — telegram-commandcode

Two deliverables in one repository:

1. index.js — MCP stdio server, agent → Telegram. This is the primary product and the part that works with every MCP client.
2. telegram_commandcode/ — Python Telegram bot, Telegram → cmd CLI. Coupled to Command Code's closed-source argument surface.

legacy/ holds the original Node bot. Archived, unsupported, excluded from the npm package. Do not add features there.

Status: daemon frozen, MCP server maintained

The MCP server is where new work goes. The bot daemon is feature-frozen at 2.2.0: fix bugs, do not add commands or flags. Command Code now ships its own Telegram bridge (/rc, announced 2026-09-29) for its own sessions, so a new daemon feature would be re-implementing a vendor feature. The daemon remains for self-hosting a bot on a server and for driving a CLI from chat.

Repository map

index.js                      MCP server (7 tools, SDK 1.29 schemas)
package.json                  npm metadata, bin, npm test
scripts/build-skill.mjs       builds dist/telegram-bridge-skill.zip
skill/                        publishable SKILL.md + 4 reference docs
test/mcp.test.mjs             node:test protocol tests (spawns the server)
tests/                        pytest suite (163 tests, no network, no `cmd`)
legacy/                       old Node bot + Discord bridge (archived)
deploy/                       systemd unit

telegram_commandcode/
├── bot.py                    PTB Application, 48-command menu, startup
├── session.py                ChatSession dataclass + file-backed SessionStore
├── executor.py               async `cmd` runner, per-chat process tracker
├── chunking.py               code-fence-aware 4096-char splitter
├── formatter.py              MarkdownV2 escaping, table rendering
├── gateway/
│   ├── gateway.py            BotGateway: locks, rate limits, identity
│   ├── router.py             access control, group mention logic, dispatch
│   ├── sender.py             send/edit with parse fallback + flood control
│   ├── processor.py          enqueue → per-chat lock → streaming pipeline
│   └── media.py              download, transcribe, auto-attach MEDIA: paths
└── commands/
    ├── router.py             dispatch table (48 entries, TG→CC name map)
    ├── base.py               shared send_md/run_cli/config/state helpers
    ├── info_cmds.py          12 commands
    ├── session_cmds.py        9 commands
    ├── config_cmds.py         7 commands
    ├── prompt_cmds.py        11 commands
    └── cli_cmds.py            8 commands