telegram-acp-bot 0.1.0

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

Telegram ACP bot

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

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

Status

This project is in alpha and under heavy active development.

Development has included extensive use of gpt-5.3-codex.

Quick Start

Run directly without installing via uvx:

uvx --from git+https://github.com/mgaitan/telegram-acp-bot 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 --from git+https://github.com/mgaitan/telegram-acp-bot acp-bot

Current interaction capabilities:

• /new [workspace], /resume [N|workspace], /session, /cancel, /stop, /clear, /restart [N [workspace]]
• Interactive permission prompts with inline buttons (Always, This time, Deny)
• Plain text prompts
• Tool activity updates are sent as separate messages per ACP tool kind
• 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.
• Common labels are 💡 Thinking, ⚙️ Tool call, 📖 Reading, ✏️ Editing, and 🔎 Searching.
• Permission prompts for risky actions are sent as independent messages with inline buttons.
• 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).

Telegram Bot Token

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

Agent Command

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 --from git+https://github.com/mgaitan/telegram-acp-bot acp-bot

Development

• Install dependencies with uv sync.
• Then run uv run 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