This project provides a Telegram bot that bridges user messages to a local Claude Code instance, enabling remote interaction and receiving AI-generated responses directly within Telegram. It targets Claude Code users seeking a convenient, conversational interface for the AI model.

How It Works

The system orchestrates communication via a bridge server that listens for Telegram webhooks. Upon receiving a message, it injects the prompt into a persistent Claude Code session managed by tmux using tmux send-keys. Claude Code's custom "Stop" hook is configured to capture the generated transcript upon completion. The bridge server then reads this transcript and sends the AI's response back to the user via Telegram. A pending file mechanism ensures the bot only replies to messages initiated through Telegram.

Quick Start & Requirements

• Prerequisites: tmux, cloudflared.
• Installation: Clone the repository, set up a Python virtual environment (e.g., using uv), and install dependencies (uv pip install -e .).
• Setup: Requires creating a Telegram bot via @BotFather to obtain a token. Configure Claude Code by copying the provided send-to-telegram.sh hook script, setting the bot token within it, making it executable, and updating ~/.claude/settings.json to register the hook. Start Claude Code within a tmux session (tmux new -s claude && claude --dangerously-skip-permissions). Run the bridge script (python bridge.py after setting TELEGRAM_BOT_TOKEN). Expose the bridge locally using cloudflared tunnel --url http://localhost:8080. Finally, set the Telegram webhook URL using the provided curl command.
• Links: No external documentation links provided.

Highlighted Details

• Bot Commands: Supports /status, /clear, /resume, /continue_, /loop <prompt>, and /stop for session management and interaction control.
• Environment Variables: Key variables include TELEGRAM_BOT_TOKEN (required), TMUX_SESSION (default: claude), and PORT (default: 8080).

Maintenance & Community

No specific details regarding maintainers, community channels (e.g., Discord, Slack), or project roadmap are present in the README.

Licensing & Compatibility

The repository's README does not specify a software license. This omission prevents clear determination of usage rights, modification permissions, and compatibility for commercial or closed-source integration.

Limitations & Caveats

This project necessitates a locally running, tmux-managed Claude Code instance and requires configuring Claude Code's hooks. It utilizes the --dangerously-skip-permissions flag for Claude Code, which may pose security risks. The setup is multi-step and relies on external services like Telegram and Cloudflare Tunnel for functionality. The absence of a license is a significant blocker for assessing compatibility and adoption.