Telegram ACP bot

The agent works on your computer. You control it from Telegram.

A Telegram bot that brings the Agent Client Protocol (ACP) to your pocket.

Software is changing incredibly fast, and we no longer need to write every line of code by hand. To interact with an agent, a simple and friendly chat interface is enough, and you already carry one on your phone.

ACP is the open protocol adopted by the industry to connect user interfaces to AI agents such as Codex, Claude Code, Gemini CLI, and many others that work on your machine.

Telegram ACP bot is a full-featured, open-source ACP client that allows you to control your agent wherever you are. The good part? You can start an agent session on your computer from your preferred editor/CLI/IDE and continue it later on Telegram, or do it the other way around.

Don’t watch the computer. Watch the sky.

Start with:

TELEGRAM_BOT_TOKEN=123456:abc ACP_AGENT_COMMAND="your acp capable agent" uvx telegram-acp-bot

Feature Highlights

If you want the quickest tour of what the bot can do, these are good places to start.

• Reply With Attachments explains how the agent can reply with images and files in the same Telegram chat.

• How The UX Works shows how scheduled tasks work as conversational follow-ups instead of technical status messages.

• 7. Busy-state handling covers queued messages and the Send now flow when the agent is already busy.

• MCP Integration gives the broader picture of the internal MCP tools that power those features.

Documentation

• How To Use The Bot From Telegram
  • 1. Start working (implicit session)
  • 2. Start or switch sessions with /new
  • 3. Resume an existing ACP session
  • 4. Inspect current session
  • 5. Cancel, stop, and clear
  • 6. Switch activity mode
  • 7. Busy-state handling
  • 8. Inspect and cancel scheduled follow-ups
  • 9. Restart bot process (dev workflow)
  • Notes
  • Logging and traceability
• Deferred Follow-ups
  • What Exists Today
  • How The UX Works
  • Relative And Absolute Time Inputs
  • Session Behavior
  • Inspecting And Cancelling Scheduled Work
  • A Note About Multiple MCP Calls
  • Related Pages
• Agent Setup
  • Quick compatibility map
  • Gemini CLI (native ACP)
  • Codex CLI (via adapter)
  • GitHub Copilot CLI (native ACP)
  • Claude Agent / Claude Code (via adapter)
  • Other agents
• CLI Reference
  • Arguments
  • Notes
  • register-commands
• MCP Integration
  • What The Tools Enable
  • How It Is Implemented
  • Reply With Attachments
  • Schedule Tasks
  • Session Routing
  • Why You May See Multiple Tool Calls
  • Example Sequence
  • Current Limits
• Configuration
  • Example .env
  • MCP behavior
  • MCP channel environment variables
• Keeping the demo video fresh
  • How it works
  • Recording a new video
  • Changing the script
  • Adding a new demo scenario
  • File reference
• About this documentation
  • How to contribute
  • Including diagrams
  • Linking to the repo
  • How to build the documentation
  • How the documentation is published online
• Contributing
  • Environment setup
  • Development
  • Releases
• Contributor Covenant Code of Conduct
  • Our Pledge
  • Our Standards
  • Enforcement Responsibilities
  • Scope
  • Enforcement
  • Enforcement Guidelines
  • Attribution