A Telegram bot that implements the Agent Client Protocol to interact with AI agents.

Project documentation: https://mgaitan.github.io/telegram-acp-bot/

This project is in alpha and under active development. Development has included extensive use of AI agents. Human and agents contributions are welcome.

Some of the most useful capabilities are documented here:

• Reply with attachments: https://mgaitan.github.io/telegram-acp-bot/mcp.html#mcp-feature-attachments
• React to messages: https://mgaitan.github.io/telegram-acp-bot/mcp.html#mcp-feature-reactions
• Scheduled tasks: https://mgaitan.github.io/telegram-acp-bot/deferred_followups.html#deferred-followups-ux
• Queue messages when the agent is busy: https://mgaitan.github.io/telegram-acp-bot/how-to.html#how-to-busy-queue
• Internal MCP tools overview: https://mgaitan.github.io/telegram-acp-bot/mcp.html

Run directly without installing via uvx:

uvx telegram-acp-bot --help

Run the latest development version from git:

uvx git+https://github.com/mgaitan/telegram-acp-bot --help

Run the bot with a real ACP agent:

TELEGRAM_BOT_TOKEN=123456:abc \
ACP_AGENT_COMMAND="npx @zed-industries/codex-acp" \
uvx telegram-acp-bot

Current interaction capabilities:

• /new [workspace], /resume [N|workspace], /session, /cancel, /stop, /clear, /restart [N [workspace]]
• /mode [normal|compact|verbose] to switch the activity display per chat
• Interactive permission prompts with inline buttons (Always, This time, Deny)
• Plain text prompts
• Image and document attachments from Telegram messages
• ACP file:// resources are sent as attachments when they resolve to files inside the active workspace
• Agent markdown output (with fallback to plain text when Telegram rejects entities)

Message flow:

• The bot sends activity blocks while the prompt is running.
• Activity display modes:
  • normal: separate activity messages, no streaming edits.
  • compact: one in-progress status message that becomes the final answer.
  • verbose: append-only in-place streaming for active reply text and tool activity.
• Common labels are 💡 Thinking, ⚙️ Running, 📖 Reading, ✏️ Editing, ✍️ Writing, 🌐 Searching web, and 🔎 Querying.
• Permission prompts for risky actions are sent as independent messages with inline buttons.
• In normal, the final answer is sent as a separate message after activity blocks.
• If the final text is empty, no dummy "(no text response)" message is sent.

For development, /restart stops polling and relaunches the process. If ACP_RESTART_COMMAND (or --restart-command) is configured, that command is used (recommended when running with uv run ... and extra flags). Otherwise, it falls back to re-execing the current process (sys.executable + sys.argv).

Create your token with @BotFather:

1. Open BotFather and run /newbot.
2. Choose a bot name and username.
3. Copy the token returned by BotFather.

Store the token in your local .env file (gitignored):

At least one allowlist entry is required (TELEGRAM_ALLOWED_USER_IDS or TELEGRAM_ALLOWED_USERNAMES).

TELEGRAM_BOT_TOKEN=123456:abc
TELEGRAM_ALLOWED_USER_IDS=123456789
# TELEGRAM_ALLOWED_USERNAMES=alice,@bob
ACP_AGENT_COMMAND="npx @zed-industries/codex-acp"
ACP_RESTART_COMMAND="uv run telegram-acp-bot --telegram-token <TOKEN> --agent-command \"npx @zed-industries/codex-acp\""
ACP_PERMISSION_MODE=ask
ACP_PERMISSION_EVENT_OUTPUT=stdout
ACP_STDIO_LIMIT=8388608

Set ACP_AGENT_COMMAND to the ACP-compatible agent command you want the bot to run.

Example:

ACP_AGENT_COMMAND="npx @zed-industries/codex-acp"

To install the tool permanently:

uv tool install telegram-acp-bot

• Install dependencies with uv sync.
• Then run uv run telegram-acp-bot
• New dependency releases are delayed by one week via uv cooldown ([tool.uv].exclude-newer = "1 week"), with per-package overrides when required (for example, ty).
• Run the QA bundle with ty:

uv run ty check