Telegram Claude + Codex: Remote Coding Agents via Telegram
TypeScriptBunTelegram BotClaude CodeOpenAI CodexAIgrammyGroq
A Telegram bot that runs Claude Code or OpenAI Codex on your VPS and streams responses back to chat. Switch providers at runtime, with per-provider sessions, voice messages, plan mode, compose mode, and message queuing.
Telegram Claude + Codex brings the full power of coding-agent CLIs to Telegram, enabling remote code assistance from any device. Instead of SSH-ing into a VPS, you simply send a message in Telegram and get streamed responses with full context awareness — from either Claude Code or OpenAI Codex, switchable at runtime.
The bot spawns the active provider's CLI in your project directories, maintains per-provider session continuity for follow-up conversations, and handles everything from voice transcription to plan mode approval — all through Telegram's chat interface.
Key Features
Multi-Provider
- Switch between Claude Code and OpenAI Codex at runtime via
/provider - Sessions and capabilities tracked per provider
- Active provider shown in
/status,/help, and pinned project message - Capability-aware UI adapts to each provider's features
Real-Time Streaming
- Spawns the active provider's CLI as a child process
- Streams responses back to Telegram in real-time
- Auto-splits long responses at Telegram's 4000 character limit
- Renders MarkdownV2 with plain text fallback
Project Switching
- Inline keyboard for quick project selection
- Configurable project directories
- Each project maintains its own session per provider
- Auto-unpins old project messages
Voice Messages
- Transcribes voice notes via Groq Whisper (
whisper-large-v3-turbo) - Sends transcribed text directly to the active agent
- Enables hands-free coding assistance
- Fast transcription with minimal latency
Plan Mode
- Intercepts plan mode for both providers (Claude's
ExitPlanMode, Codex's.codex/plans/convention) - Presents plans for approval via Telegram buttons
- Execute in new session, keep context, or modify with feedback
- Full control over code changes from mobile
Compose Mode
/composeto batch multiple messages into a single prompt- Supports text, voice, forwarded messages, files, and photos
/sendto dispatch the batch,/cancelto discard- Useful for forwarding context from other chats
Architecture
The bot is built as a single TypeScript application running on Bun, designed for deployment on a VPS alongside the projects it manages.
Message Processing Pipeline
Messages flow through a sequential queue to prevent race conditions when multiple messages arrive simultaneously. Each message is processed in order:
- Receive — Telegram message or voice note arrives
- Transcribe — Voice messages are converted to text via Groq Whisper
- Route — Message is directed to the active project's session for the current provider
- Stream — Agent output (and thinking) is streamed back via Telegram draft messages
- Complete — Final response is sent, session remains active for follow-ups
Session Management
- Sessions persist across messages for natural conversational flow
- Per-provider session tracking —
/historyand follow-ups stay scoped to the active provider - Resume via Claude's
-r <id>or Codex'sexec resume <id> - Git branch and open PR status shown in
/statusand response footers
Deployment
- Runs as a systemd service for automatic restart and boot persistence
- Environment-based configuration for bot tokens and project paths
- No API keys required — CLI auth is handled by
claude login/codex loginon the host - Lightweight resource footprint — only spawns the agent CLI when needed
Technology Stack
- TypeScript + Bun — Fast runtime with native TypeScript support
- grammy — Modern Telegram bot framework with middleware support
- Claude Code CLI — Anthropic's CLI tool for AI-assisted development
- OpenAI Codex CLI — OpenAI's coding agent CLI (optional second provider)
- Groq SDK — Fast voice transcription via Whisper API
- systemd — Process management and auto-restart on Linux