Guide
How to use Claude Code in Telegram
Telegram is already open on your phone, it handles voice and files well, and its bots can show buttons. That makes it a good remote control for a Claude Code agent. Here is what such a bridge has to do, and how to set up the one in AgentKennel.
What a Telegram bridge needs
Claude Code has no Telegram client of its own. To drive it from a chat, something has to run next to Claude Code on the same machine and connect the two:
- Claude must keep running between your messages, so it lives in a terminal multiplexer such as tmux on an always-on machine, not in the bot process.
- Your text goes in as keystrokes to that terminal, and the agent's output comes back as messages.
- Only you may use it. A bot that types into a terminal with shell access must ignore everyone else.
The AgentKennel bridge
AgentKennel is a self-hosted, open-source dashboard that runs many Claude Code terminals on your server. Its Telegram bridge is a bot that types your messages into the selected terminal and sends the screen back. The terminals are the same ones you see in the browser dashboard: Telegram and the browser are two windows into them.
- Owner-only. Every handler is filtered by your numeric Telegram user id; messages and button taps from anyone else are ignored.
- Voice notes are transcribed on your server with faster-whisper, then typed in.
- Buttons. When Claude asks a multiple-choice question, the options arrive as inline buttons.
- Files and images you send are saved on the server and handed to the agent as a path.
- Live progress. The agent's progress and its final answer stream back into the chat.
Set it up
This takes a few minutes once AgentKennel is installed (see the install options).
- Message BotFather in Telegram, send
/newbot, follow the prompts and copy the token it gives you. - Find your numeric Telegram user id (a number, not your @username). One way: message userinfobot, which replies with your Id.
- In the dashboard, open ⋯ → Telegram, paste the token and your user id, and press Save & start. The bot starts right away and comes back after a restart.
- Open your new bot in Telegram and send
/useto pick a terminal.
The installer never handles the token; you paste it only into your own dashboard. If you prefer configuration files, the bridge can also be set up with a .env file and a systemd user service; the Telegram setup docs on GitHub walk through it.
Commands
Plain text is typed into the selected terminal. Commands start with a slash:
| Command | What it does |
|---|---|
/use | pick a terminal from buttons (loaded ones first) |
/use <text> | pick a terminal by part of its name or its code |
/list | all terminals; the current one is marked |
/new <name> | start a new terminal and select it |
/archive | archived terminals as buttons: a tap restores one and picks it |
/read | re-read the current terminal's screen |
/esc | interrupt the agent (Escape) |
/enter | send Enter |
/compact | compact the agent's conversation |
/restart | restart Claude in the current terminal, on the same conversation |
/services | your services, with buttons to restart, stop or start each |
A typical exchange
You send /use and tap the terminal working on your API. The bot replies with its current screen. You record a voice note: "run the test suite and fix whatever fails". It is transcribed and typed in; progress streams back as the agent works. Halfway through, Claude asks whether to update a snapshot, and the choices appear as buttons. You tap one and put the phone away. Later, at a desk, you open the same terminal in the browser and scroll through everything it did.
Limits worth knowing
- In AgentKennel's Docker sandbox, voice notes don't work: the image has no faster-whisper or ffmpeg, so they get an error reply. Text and files work.
- Telegram shows text, not a live terminal. For long output or careful reading, open the terminal in the browser; it is the same session.
- The bot answers one owner. Other people need their own setup.