telecode 0.1.6

Telegram webhook server that runs Claude Code or Codex in the background

Telecode

Your AI Terminal Inside Telegram — Bridge Telegram with Claude Code and Codex. Execute commands, analyze images, transcribe voice, and chat with AI—all from your favorite messenger.

✨ Features

• 🤖 Dual AI Engines — Switch between Claude Code and Codex on the fly
• 📡 MCP Server — Expose AI tools via Model Context Protocol for remote agent access
• 🖼️ Vision Processing — Send screenshots and images for AI analysis
• 🎤 Voice Transcription — Whisper-powered voice note transcription
• 🔊 Text-to-Speech — Fish Audio integration for audio responses
• ⚡ Real-time Webhooks — Instant message processing via Telegram webhooks
• 🔒 Access Control — Whitelist users by ID or username
• 💬 Persistent Sessions — Conversations preserved across messages

🚀 Quick Start

Install

pip install telecode

Run

telecode

On first run, you'll be prompted for:

• Telegram Bot Token (get it from @BotFather)
• ngrok Auth Token (optional, for auto-tunneling)

That's it! Find your bot in Telegram and start chatting.

📡 MCP Server (NEW)

Telecode can expose AI tools via the Model Context Protocol, allowing remote agents to access your local AI engines:

Enable MCP Server

telecode --enable-mcp

The server will display your MCP connection URL:

+----------------------------------------------------+
| MCP Server Configuration:                          |
|                                                    |
| URL: https://your-tunnel.ngrok-free.app/mcp/      |
| (Public ngrok URL - share with remote MCP clients)|
|                                                    |
| Available Tools:                                   |
|   - local_claude_code: Execute Claude Code CLI     |
|   - local_codex: Execute Codex CLI                 |
|   - local_cli: Execute shell commands              |
+----------------------------------------------------+

MCP Tools

• local_claude_code — Execute prompts with Claude Code CLI
• local_codex — Execute prompts with Codex CLI
• local_cli — Run shell commands on your server

MCP clients can connect to your server and use these tools remotely. Sessions are independent from Telegram, allowing simultaneous use.

💬 Telegram Commands

Command	Description
/engine	Show current AI engine
/claude	Switch to Claude Code
/codex	Switch to Codex
/cli <cmd>	Execute shell command
/tts_on	Enable TTS audio responses
/tts_off	Disable TTS responses

🎯 Usage Examples

Chat with AI

Simply send any message to interact with the current engine:

You: Write a Python function to reverse a string

Bot: Here's a simple function:

def reverse_string(s):
    return s[::-1]

Analyze Images

Send a photo with a caption:

[Screenshot of error]
Caption: "What's causing this bug?"

Bot: This is a NullPointerException at line 42...

Execute Commands

/cli git status

Bot: On branch main
     Your branch is up to date...

Voice Messages

Hold the mic button, speak your prompt, release. The bot transcribes and responds.

⚙️ Configuration

Configuration is stored in .telecode (local) or ~/.telecode (global):

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
TELECODE_ENGINE=claude
TELECODE_ALLOWED_USERS=123456789,@username
TELECODE_ENABLE_MCP=1
TELECODE_VERBOSE=1

Key Configuration Options

Variable	Description	Default
TELEGRAM_BOT_TOKEN	Bot token from @BotFather	Required
TELEGRAM_TUNNEL_URL	Public webhook URL	Auto via ngrok
TELECODE_ENGINE	Default engine: claude or codex	claude
TELECODE_ENABLE_MCP	Enable MCP server	0
TELECODE_ALLOWED_USERS	User whitelist (IDs/@usernames)	(empty = all)
TELECODE_VERBOSE	Enable verbose logging	0
TELECODE_TTS	Enable TTS responses	0

🔐 Access Control

Restrict bot access to specific users:

# By user ID (get from @userinfobot)
TELECODE_ALLOWED_USERS=123456789,987654321

# By username
TELECODE_ALLOWED_USERS=@alice,@bob

# Mixed
TELECODE_ALLOWED_USERS=123456789,@alice

Leave empty to allow all users.

🛠️ Development

# Clone and install
git clone https://github.com/polinom/telecode.git
cd telecode
pip install -e .

# Run with auto-reload
telecode --reload -v

# Run tests
pytest -q

CLI Options

telecode --help

Options:
  --host HOST          Host to bind (default: 0.0.0.0)
  --port PORT          Port to bind (default: 8000)
  --reload             Enable auto-reload (dev mode)
  --engine {claude,codex}  Default engine
  --no-ngrok           Disable ngrok auto-start
  --enable-mcp         Enable MCP server
  -v, --verbose        Enable verbose logging

🏗️ Architecture

┌─────────────┐
│  Telegram   │
│   Bot API   │
└──────┬──────┘
       │ HTTPS
       ▼
┌──────────────┐
│ ngrok Tunnel │
└──────┬───────┘
       │
       ▼
┌──────────────────┐     ┌─────────────┐
│  FastAPI Server  │────▶│ MCP Clients │
│  (Port 8000)     │     └─────────────┘
└──────┬───────────┘
       │
   ┌───┴───┐
   ▼       ▼
┌────────┐ ┌───────┐
│ Claude │ │ Codex │
└────────┘ └───────┘

📚 Documentation

• User Guide — Website with examples
• CLAUDE.md — Developer guide for AI assistants
• GitHub Issues — Bug reports and feature requests

🔧 Troubleshooting

Bot doesn't respond

• Check webhook URL is accessible
• Run with -v for verbose logs
• Verify bot token with @userinfobot

Voice messages fail

pip install openai-whisper
brew install ffmpeg  # macOS

Invalid bot token error

The CLI will detect invalid tokens and prompt for a new one automatically.

ngrok authentication failed

Get your auth token from ngrok.com and paste when prompted.

📄 License

MIT — See LICENSE for details.

---

Contributing: Issues and PRs welcome! • Security: Never commit tokens or API keys

⭐ Star on GitHub if you find this useful!