Control any coding agent through Telegram.

Screenshots	Screenshots	Screenshots
Talking with agent. Handle multiple sessions with tabs and threads.	Uploading artifacts. Use telegraph to view your markdown files, or let it upload images or files.	Slash commands. Manage your sessions with ease, set models and permissions, or use agent's commands.

• Get notifications and view real-time progress on your phone
• Give new tasks to agent even you're away from computer
• Works with any agent that supports ACP. This is almost any agent, including claude code, codex, opencode and cursor.
• Handle multiple sessions simutaniously, in different telegram tabs

Method 1: Use cargo binstall (not recommended)

cargo binstall requires me to manually bump version numbers and do a release, and there's no way to upload a binary on push. Therefore, the version on binstall can be quite old.

cargo binstall telegram-acp
telegram-acp

Method 2: Use via nix

nix run github:SuperKenVery/Telegram-ACP

The flake exposes a Home Manager module for running the daemon as a user service:

{
  imports = [ inputs.telegram-acp.homeManagerModules.default ];

  services.telegram-acp = {
    enable = true;
    botTokenFile = "/run/secrets/telegram-acp-bot-token";
    chatId = 123456789;
    defaultAgent = "codex";
    agents.codex = "codex --acp";
  };
}

Method 3: Compile from source

git clone https://github.com/SuperKenVery/Telegram-ACP.git
cd Telegram-ACP
./dev-loop.fish

On Telegram, use @botfather to create a new bot and get your bot token. You should also enable threaded mode in bot settings.

Create ~/.config/telegram-acp/config.toml:

bot_token = "<telegram-bot-token>"
chat_id = 123456789
default_agent = "claude"

# Control tray icon (menu bar on macOS)
# true: Use tray icon; false: Don't use
# omit: Try to create tray icon, fail silently
# tray = false

[claude]
cmd = "claude-agent-acp"

[codex]
cmd = "codex --acp"
# socket_path = "/tmp/telegram-acp.sock"
# telegraph_author = "Your Name"

Env overrides are also supported:

• TELEGRAM_ACP_BOT_TOKEN
• TELEGRAM_ACP_CHAT_ID
• TELEGRAM_ACP_SOCKET_PATH
• TELEGRAM_ACP_DEFAULT_AGENT
• TELEGRAM_ACP_TELEGRAPH_AUTHOR

CLI ──(Unix socket IPC)──> Daemon ──> ACP Agent subprocesses (stdin/stdout)
                              │
                              └──> Telegram Bot API (topics, messages)

Per session:

1. Creates/uses a Telegram forum topic (or threaded private chat topic)
2. Spawns an ACP agent subprocess
3. Routes user messages -> agent and agent events -> Telegram

Use the included mock ACP binary to test Telegram/IPC plumbing without a real coding agent:

cargo run -- daemon

Configure it as an agent in your config:

default_agent = "mock"

[mock]
cmd = "./target/debug/mock_agent"

Then you can send some ACP updates as text via telegram, and it would send those updates to our daemon.

• Enable Threaded Mode in BotFather
• For supergroups, forum topics should be enabled

• agent-client-protocol types are !Send, so ACP work is pinned to a tokio::task::LocalSet
• Telegram dispatcher + IPC server run with tokio::spawn and communicate through channels
• Each session has two unbounded channel pairs:
  • user_tx/user_rx: user text into prompt loop
  • event_tx/event_rx: agent output back to Telegram consumer
• Notification behavior is intentional:
  • first and final message notify
  • intermediate streaming messages are silent
• Permission prompts are auto-approved by choosing the first allow option

src/
  main.rs          CLI entrypoint (`daemon`, `new`, `status`)
  config.rs        Config loading (TOML + env overrides)
  daemon.rs        Daemon state, session lifecycle, LocalSet bridge
  session.rs       Prompt loop (PromptRequest orchestration)
  acp.rs           ACP client integration + subprocess handling
  telegram.rs      Bot dispatcher, topic routing, event consumer
  telegraph.rs     Telegraph helpers (account/page publishing)
  ipc.rs           Unix socket NDJSON daemon/client protocol
  types.rs         Shared command/response/event types
  formatting.rs    Telegram HTML escaping + message splitting
  bin/mock_agent.rs Mock ACP agent for local testing

GPL v3