{"id":30839119,"url":"https://github.com/coffebar/telegram-claude-relay","last_synced_at":"2025-09-06T18:55:15.173Z","repository":{"id":307572494,"uuid":"1027703449","full_name":"coffebar/telegram-claude-relay","owner":"coffebar","description":"A Telegram bot that acts as a relay between Telegram and Claude Code running in a tmux pane.","archived":false,"fork":false,"pushed_at":"2025-08-13T17:20:50.000Z","size":1136,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-13T19:29:34.753Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coffebar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-28T12:06:01.000Z","updated_at":"2025-08-13T17:20:53.000Z","dependencies_parsed_at":"2025-08-01T01:06:00.396Z","dependency_job_id":null,"html_url":"https://github.com/coffebar/telegram-claude-relay","commit_stats":null,"previous_names":["coffebar/telegram-claude-relay"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/coffebar/telegram-claude-relay","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coffebar%2Ftelegram-claude-relay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coffebar%2Ftelegram-claude-relay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coffebar%2Ftelegram-claude-relay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coffebar%2Ftelegram-claude-relay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coffebar","download_url":"https://codeload.github.com/coffebar/telegram-claude-relay/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coffebar%2Ftelegram-claude-relay/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273948884,"owners_count":25196400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-06T02:00:13.247Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-06T18:55:10.923Z","updated_at":"2025-09-06T18:55:15.161Z","avatar_url":"https://github.com/coffebar.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Code Telegram Bot\n\nA Telegram bot that acts as a relay between Telegram and Claude Code running in a tmux pane.\n\n## What it does\n\n- Receives messages from Telegram\n- Forwards them to Claude Code in a tmux pane\n- Track Claude activity (including thinking steps) via hooks\n- Returns Claude's responses back to Telegram\n- Parse Claude's permissions options and send them as inline keyboard buttons\n\n## Screenshot\n\n![Telegram Bot Interface](Screenshot_Telegram.png)\n\n## Setup\n\n### Prerequisites\n\n- Python 3.8+\n- `tmux` installed\n- Claude Code CLI installed and authenticated\n\n### 1. Create Your Telegram Bot (Required)\n\n1. Message [@BotFather](https://t.me/BotFather) on Telegram\n2. Send `/newbot` and follow the prompts\n3. Save your bot token (looks like: `1234567890:ABCdefGHIjklMNOpqrsTUVwxyz`)\n4. Get your Telegram user ID (message [@userinfobot](https://t.me/userinfobot))\n5. Optional: send `/setuserpic` command to @BotFather, select your bot and upload `BotAvatar.svg` as a photo to change avatar image.\n\n### 2. Installation\n\n```bash\n# Clone and enter directory\ngit clone https://github.com/coffebar/telegram-claude-relay\ncd telegram-claude-relay\n\n# Configure your bot\ncp .env.example .env\n# Edit .env with your bot token and user ID from step 1\n\n# Complete setup (dependencies + Claude hooks)\nmake setup-full\n```\n\n### 3. Start Claude in tmux\n\nOpen a tmux session in any directory where you want to work:\n\n```bash\n# Start tmux and Claude\ntmux new-session -s my-coding-session\ncd /path/to/your/project\nclaude\n```\n\n### 4. Run the Bot\n\n```bash\n# In a separate terminal\ncd telegram-claude-relay\nmake run\n# or specify a .env file for a specific bot:\nmake run 2          # For .env.2\n```\n\n## Usage\n\n1. Start Claude in any tmux session (in your project directory)\n2. Run the bot with `make run`\n3. Message your bot on Telegram\n4. Your messages go directly to Claude\n5. Claude's responses come back with live tool updates\n\nThe bot uses Claude Code hooks to provide real-time tool notifications and live-updating status messages.\n\n### Bot Commands\n\n- `/start` - Show welcome message\n- `/esc` - Send ESC key to Claude (useful for canceling operations or exiting modes)\n- `/self_update` - Update bot from GitHub and restart automatically\n- Any other text - Sent directly to Claude (including `/clear`, `/compact`, etc.)\n\n## Features\n\n- **Real-time Tool Transparency**: See exactly what Claude is doing with full code display (including subagent communications)\n- **Interactive Permission Handling**: Approve/deny Claude's actions with inline keyboard buttons\n- **Live Status Updates**: Watch Claude's thinking process and tool usage in real-time\n- **Hook-based Integration**: Deep integration with Claude Code via Unix socket communication\n- **Smart Pane Discovery**: Automatically finds Claude running in any tmux pane\n- **Whitelist Authentication**: Simple user ID based access control (configure in ALLOWED_USERS)\n- **Rate Limiting**: Built-in protection against spam (60 requests/minute + burst protection)\n- **Automated Setup**: One-command installation with automatic Claude hooks configuration\n- **System Monitoring**: Built-in status checks and log streaming\n- **Diff Formatting**: Code edits displayed in unified diff format for easy review\n- **CWD-based Hook Filtering**: Only processes hooks from Claude instance in the tmux session\n- **Smart Format Conversion**: Automatically converts Claude's standard markdown to Telegram-compatible format by using `telegramify-markdown`\n- **Self-Update Capability**: Easily update the bot code from GitHub with `/self_update` command\n\n## Configuration\n\n- `TELEGRAM_BOT_TOKEN` - Your bot token\n- `TELEGRAM_BOT_USERNAME` - Your bot username\n- `ALLOWED_USERS` - Comma-separated Telegram user IDs\n- `PANE` - Target tmux pane (format: `session:window.pane`, leave empty for auto-discovery)\n- `FILTER_HOOKS_BY_CWD` - Filter hooks by working directory (default: `true`)\n- `DEBUG` - Enable debug logging (optional)\n\n## Multi-Bot Support\n\nRun multiple bots monitoring different projects:\n\n```bash\n# Create separate config for each bot\ncp .env.example .env.2           # Numbered bot config\ncp .env.example .env.prod        # Named bot config\n\n# Run specific bot\nmake run                          # Default bot (uses .env)\nmake run 2                        # Bot 2 (uses .env.2)\nmake run prod                     # Production bot (uses .env.prod)\n```\n\n## Commands\n\n```bash\nmake setup       # Create venv and install dependencies\nmake run         # Run the bot (or make run \u003cname\u003e for specific bot)\nmake stop        # Stop the bot gracefully\nmake restart     # Trigger bot restart in same terminal (sends SIGUSR1)\nmake clean       # Remove venv\nmake self-update # Update the app from GitHub (git pull --rebase --autostash)\nmake format      # Format all Python files with black and isort\nmake lint        # Run linting checks with ruff\nmake format-check# Check if files are properly formatted\nmake setup-full  # Complete setup (dependencies + Claude hooks)\nmake status      # Check tmux session, hooks, and bot status\nmake logs        # Tail bot logs with live updates\nmake install-hooks # Install Claude Code hooks\nmake uninstall-hooks # Uninstall Claude Code hooks\nmake update-tool-schemas # Update tool schemas documentation from logs\nmake help        # Show available commands\n```\n\n## How it works\n\n1. Bot receives Telegram message\n2. Sends message to tmux pane via `tmux send-keys`\n3. Claude Code triggers hooks to send updates back to the bot\n4. Bot processes updates and sends them back to Telegram\n5. You see Claude's responses and tool usage in real-time\n\nThe bot now includes comprehensive tool transparency with specific formatting for each Claude tool (Bash, Edit, Read, Write, etc.), making it easy to see exactly what Claude is doing at each step.\n\n**Note:** You can interact with the same Claude session from anywhere - directly in tmux locally, via SSH from another machine, or through this Telegram bot.\n\n### Claude Code Hooks Integration\n\nTrack ALL Claude activity including:\n\n- 🔧 Tool usage (file edits, commands, etc.)\n- 🤖 Regular responses with thinking steps\n- Asking for permission to use tools\n\n## Troubleshooting\n\n### Claude not running in tmux (most common issue)\n\n```bash\n# Check if tmux sessions exist\ntmux list-sessions\n\n# Check if Claude is running in a specific session\ntmux capture-pane -t session-name -p\n\n# If no Claude session, create one:\ntmux new-session -d -s claude-session\ntmux send-keys -t claude-session \"claude\" Enter\n```\n\n### Bot won't start\n\n- Check `.env` file exists and has correct values\n- Run `make setup` to reinstall dependencies\n- Verify Telegram bot token is valid\n\n### No responses from bot\n\n- **First check**: Is Claude actually running in tmux?\n- Check bot logs for connection errors\n- Verify your Telegram user ID is in `ALLOWED_USERS`\n- Test Claude directly in tmux: `tmux send-keys -t your-pane \"test message\" Enter`\n\n### Tool Usage Transparency\n\n- **Evidence-Based Tool Messages**: Scientific approach to tool transparency\n  - **Bash**: `💻 **Bash:** docker ps - Show running Docker containers`\n  - **LS**: `📂 **Listing:** /path/to/directory`\n  - **Edit**: `✏️ **Editing:** /path/to/file - replacing: old text...`\n  - **TodoWrite**: `📝 **Managing todos:** 4 items`\n  - **Read**: `📖 **Reading:** /path/to/file (lines 0-20)`\n  - **Write**: `✍️ **Writing:** /path/to/file (1234 chars)`\n  - **Grep**: `🔍 **Searching:** pattern in /path (content)`\n  - **Glob**: `🗂️ **Finding files:** *.py`\n  - **MultiEdit**: `✏️ **Multi-editing:** /path/to/file (3 changes)`\n  - **WebSearch**: `🌐 **Web Search:** search terms`\n  - **Unknown tools**: Generic display until verified\n- [ ] **Adding New Tools (Future)**: How to add support for new tools\n  1. **Trigger the tool** - Use Claude Code to execute the new tool\n  2. **Check logs** - Look for `tool_input_full` in `telegram-claude-bot.log`\n  3. **Extract structure** - Find the exact parameter names and types\n  4. **Update code** - Add verified parameters to `src/claude/conversation_monitor.py`\n  5. **Test** - Verify the new tool shows detailed information\n\n  Example verification command:\n\n  ```bash\n  grep -A 1 '\"tool_name\": \"NewTool\"' telegram-claude-bot.log | grep \"tool_input_full\"\n  ```\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoffebar%2Ftelegram-claude-relay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoffebar%2Ftelegram-claude-relay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoffebar%2Ftelegram-claude-relay/lists"}