Claude Code Telegram Agent Bot

Run Claude Agent SDK on Telegram. Multi-turn chat per user, streaming replies, voice input, file uploads, plan mode, MCP — all in your favourite messenger.

---

✨ Highlights

• 🪄 Custom slash commands — killer feature. Drop a *.md file into commands_dir, get a Telegram bot command. Body is the prompt; $ARGUMENTS substitutes whatever the user typed. Ship /recall, /today, /standup, /capture to your team without touching code. See COMMANDS.md.
• 💬 Per-chat session memory — every chat owns a live ClaudeSDKClient; /new starts fresh.
• ⚡ Token-by-token streaming — animated draft via Bot API sendMessageDraft.
• 🎙️ Voice & audio in — transcribed by Groq Whisper, fed into the agent.
• 📎 Photo / document / sticker uploads — Claude reads files via Read; albums coalesced into one turn.
• 🛡️ Permission gate — Allow / Deny / Always-allow-this-session inline buttons for every tool call.
• 🧠 Plan mode — /plan <task> engages permission_mode="plan"; Approve / Reject keyboard for ExitPlanMode.
• ❓ AskUserQuestion → keyboards — single- and multi-select inline polls returned to Claude as plain text.
• 🌍 20 languages out of the box — ar bn de en es fr hi id ja ko mr pt ru sw ta te tr ur vi zh.
• 🔒 Fail-closed access control — per-bot whitelist / blacklist / open mode.
• 🤖 Run many bots in one process — asyncio.gather over a <name>: BotConfig map.

🚀 Quick start

git clone <repo-url> agent-bot && cd agent-bot
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

claude login                                       # one-off Claude Code auth
cp src/config/config.example.json src/config/config.json
# edit: telegram_bot_token + allowed_chat_ids

python -m src.bot                                  # or: agent-bot

Don't know your chat_id? Leave allowed_chat_ids: [], message the bot — the refusal contains it. Add it back, restart.

🧭 Bot commands

/start /new /context /plan /cancel /stop /mode /model /mcp /info /whoami /help + any user-defined slash commands from commands_dir.

Drop *.md files into commands_dir to expose reusable workflows (/recall, /today, /standup, …) with $ARGUMENTS substitution. See COMMANDS.md.

📚 Documentation

File	What's inside
INSTALLATION.md	Step-by-step setup, multi-bot config, troubleshooting.
CONFIG.md	Every BotConfig field — type, default, validation, env override.
COMMANDS.md	Custom slash commands: frontmatter, $ARGUMENTS, examples.
AGENTS.md	Architecture reference for LLM agents working in this repo.
CLAUDE.md	Short orientation pinned to the repo for Claude Code.

🛠 Tech

aiogram 3 · claude-agent-sdk · pydantic 2 · telegramify-markdown · Groq Whisper.

Full deps + dev tooling (ruff, mypy, pyright, bandit, pip-audit, pytest) declared in pyproject.toml.

📄 License

MIT — © 2026 Eugene Myazin.