Telegram AI Agent provides an open-source Telegram bot runtime for running Claude Code or Codex CLI tools on a VPS. It uses Telegram as a remote control interface for agentic coding tasks, allowing users to manage projects via private chats or group forum topics. Each topic binds to a specific directory on the server, such as /home/user/projects/my-app, enabling persistent workflows from a phone or any Telegram client. The project, hosted at https://github.com/pavel-molyanov/telegram-ai-agent, has 43 GitHub stars and uses Python as its primary language.

The bot operates on the same Linux machine as the Claude Code or Codex CLI. When a message arrives, it verifies the sender's Telegram user ID, handles attachments like photos, documents, voice notes, or forwarded messages, resolves topic settings, and forwards the input to the agent in the designated working directory. Output streams back to Telegram, including progress updates and final results. Forum topics maintain isolation via Telegram's chat_id and thread_id, each with configurable options like cwd for the project path, mode for prompt styles, engine as claude or codex, exec_mode as tmux or subprocess, stream_mode such as verbose, live, or minimal, and optional mcp_config or model overrides.

Core features

This bot supports a focused set of interactions for remote agent control:

  • Run agents from Telegram private chats or group forum topics, with one topic per project or workflow.
  • Send text, photos, documents, voice messages (transcribed via optional Deepgram API), or batches of forwarded messages.
  • Use /tui to open a live terminal UI snapshot with controls for Enter, Esc, arrows, digits, refresh, and close.
  • Resume sessions by replying to bot messages or using /resume.
  • Agents push responses, images, and documents back to Telegram via the bundled bot MCP server.
  • Persistent tmux sessions for ongoing development or short-lived subprocesses for one-off tasks.

Requirements

A Linux VPS or machine hosts both the bot and at least one agent CLI. Key dependencies include:

  • Python 3.12 or higher.
  • uv package manager.
  • Telegram bot token from @BotFather.
  • Numeric Telegram user ID from @userinfobot.
  • Claude Code CLI (claude command) and/or Codex CLI (codex command), installed and authenticated for the bot's Linux user.
  • tmux for persistent sessions.
  • Optional Deepgram API key for voice-to-text.

Verify setup with these checks:

python3 --version
uv --version
command -v tmux
command -v claude || true
command -v codex || true

At least one of claude or codex must be available and functional under the bot's user.

Getting it running

The repository provides two setup paths: agent-assisted for simplicity if an agent CLI is already installed, or manual configuration.

Agent-assisted setup

Clone the repo and sync dependencies:

git clone https://github.com/pavel-molyanov/telegram-ai-agent.git
cd telegram-ai-agent
uv sync

Open Claude Code or Codex CLI in the repo directory and prompt it:

Set up this Telegram bot using the bot-setup skill.

Dedicated skills exist at .claude/skills/bot-setup/SKILL.md and .codex/skills/bot-setup/SKILL.md. The agent handles bot token, user ID, language, default engine, execution mode, and optional systemd service installation.

For group forum topics, prompt:

Create and configure Telegram forum topics using the topic-setup skill.

Skills are at .claude/skills/topic-setup/SKILL.md and .codex/skills/topic-setup/SKILL.md.

Manual setup

The README introduces manual steps starting with the clone and uv sync commands above. Edit configuration files directly for bot token, allowed user IDs, and topic defaults. The repo excludes private data like prompts, IDs, tokens, or machine configs, so users supply these. Run the bot via uv run bot.py or integrate with systemd after setup. Forum topics auto-configure per-thread settings once the bot starts.

Russian documentation appears in README.ru.md for non-English users.

Who this is for

Developers with a VPS and existing Claude Code or Codex CLI setups benefit most. It suits remote coding where phone-based control matters—sending tasks, files, or voice notes to a server-bound agent without desktop access. Long-running projects fit topics bound to directories, resuming via replies or /resume. Groups can collaborate in forum topics, each isolated with custom cwd, engine, or stream mode. One-off tasks use subprocess mode. Those needing live terminal interaction via /tui find it direct for input like arrows or Esc in TUI agents.

It's impractical without Linux server access or the specified CLIs. Beginners lacking CLI authentication or tmux will hit barriers.

Comparisons to similar tools

Direct CLI use of Claude Code or Codex lacks Telegram's mobility and multi-session isolation. Tools like tmux with Telegram forwarding scripts exist but miss built-in topic binding, voice support, or TUI controls. Broader bot frameworks (e.g., python-telegram-bot) require custom agent integration, while this repo bundles runtime for these specific CLIs. Heavier platforms like LangChain agents add abstraction but demand more resources than this lightweight Python bot.

Telegram AI Agent fits users tied to Claude/Codex ecosystems wanting VPS-remote access via Telegram. Source code and full details sit at https://github.com/pavel-molyanov/telegram-ai-agent.

View on GitHub →