[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-72444":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":19,"compositeScore":20,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":9,"pushedAt":9,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":15,"starSnapshotCount":15,"syncStatus":28,"lastSyncTime":29,"discoverSource":30},72444,"claude-code-telegram","RichardAtCT\u002Fclaude-code-telegram","RichardAtCT","A powerful Telegram bot that provides remote access to Claude Code, enabling developers to interact with their projects from anywhere with full AI assistance and session persistence.",null,"Python",2679,391,12,15,0,10,29,105,30,101.28,false,"main",true,[],"2026-06-12 04:01:05","# Claude Code Telegram Bot\n\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT)\n[![Python 3.11+](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.11+-blue.svg)](https:\u002F\u002Fwww.python.org\u002Fdownloads\u002F)\n\nA Telegram bot that gives you remote access to [Claude Code](https:\u002F\u002Fclaude.ai\u002Fcode). Chat naturally with Claude about your projects from anywhere -- no terminal commands needed.\n\n## What is this?\n\nThis bot connects Telegram to Claude Code, providing a conversational AI interface for your codebase:\n\n- **Chat naturally** -- ask Claude to analyze, edit, or explain your code in plain language\n- **Maintain context** across conversations with automatic session persistence per project\n- **Code on the go** from any device with Telegram\n- **Receive proactive notifications** from webhooks, scheduled jobs, and CI\u002FCD events\n- **Stay secure** with built-in authentication, directory sandboxing, and audit logging\n\n## Quick Start\n\n### Demo\n\n```\nYou: Can you help me add error handling to src\u002Fapi.py?\n\nBot: I'll analyze src\u002Fapi.py and add error handling...\n     [Claude reads your code, suggests improvements, and can apply changes directly]\n\nYou: Looks good. Now run the tests to make sure nothing broke.\n\nBot: Running pytest...\n     All 47 tests passed. The error handling changes are working correctly.\n```\n\n### 1. Prerequisites\n\n- **Python 3.11+** -- [Download here](https:\u002F\u002Fwww.python.org\u002Fdownloads\u002F)\n- **Claude Code CLI** -- [Install from here](https:\u002F\u002Fclaude.ai\u002Fcode)\n- **Telegram Bot Token** -- Get one from [@BotFather](https:\u002F\u002Ft.me\u002Fbotfather)\n\n### 2. Install\n\nChoose your preferred method:\n\n#### Option A: Install from a release tag (Recommended)\n\n```bash\n# Using uv (recommended — installs in an isolated environment)\nuv tool install git+https:\u002F\u002Fgithub.com\u002FRichardAtCT\u002Fclaude-code-telegram@v1.3.0\n\n# Or using pip\npip install git+https:\u002F\u002Fgithub.com\u002FRichardAtCT\u002Fclaude-code-telegram@v1.3.0\n\n# Track the latest stable release\npip install git+https:\u002F\u002Fgithub.com\u002FRichardAtCT\u002Fclaude-code-telegram@latest\n```\n\n#### Option B: From source (for development)\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FRichardAtCT\u002Fclaude-code-telegram.git\ncd claude-code-telegram\nmake dev  # requires Poetry\n```\n\n> **Note:** Always install from a tagged release (not `main`) for stability. See [Releases](https:\u002F\u002Fgithub.com\u002FRichardAtCT\u002Fclaude-code-telegram\u002Freleases) for available versions.\n\n### 3. Configure\n\n```bash\ncp .env.example .env\n# Edit .env with your settings:\n```\n\n**Minimum required:**\n```bash\nTELEGRAM_BOT_TOKEN=1234567890:ABC-DEF1234ghIkl-zyx57W2v1u123ew11\nTELEGRAM_BOT_USERNAME=my_claude_bot\nAPPROVED_DIRECTORY=\u002FUsers\u002Fyourname\u002Fprojects\nALLOWED_USERS=123456789  # Your Telegram user ID\n```\n\n### 4. Run\n\n```bash\nmake run          # Production\nmake run-debug    # With debug logging\n```\n\nMessage your bot on Telegram to get started.\n\n> **Detailed setup:** See [docs\u002Fsetup.md](docs\u002Fsetup.md) for Claude authentication options and troubleshooting.\n\n## Modes\n\nThe bot supports two interaction modes:\n\n### Agentic Mode (Default)\n\nThe default conversational mode. Just talk to Claude naturally -- no special commands required.\n\n**Commands:** `\u002Fstart`, `\u002Fnew`, `\u002Fstatus`, `\u002Fverbose`, `\u002Frepo`\nIf `ENABLE_PROJECT_THREADS=true`: `\u002Fsync_threads`\n\n```\nYou: What files are in this project?\nBot: Working... (3s)\n     📖 Read\n     📂 LS\n     💬 Let me describe the project structure\nBot: [Claude describes the project structure]\n\nYou: Add a retry decorator to the HTTP client\nBot: Working... (8s)\n     📖 Read: http_client.py\n     💬 I'll add a retry decorator with exponential backoff\n     ✏️ Edit: http_client.py\n     💻 Bash: poetry run pytest tests\u002F -v\nBot: [Claude shows the changes and test results]\n\nYou: \u002Fverbose 0\nBot: Verbosity set to 0 (quiet)\n```\n\nUse `\u002Fverbose 0|1|2` to control how much background activity is shown:\n\n| Level | Shows |\n|-------|-------|\n| **0** (quiet) | Final response only (typing indicator stays active) |\n| **1** (normal, default) | Tool names + reasoning snippets in real-time |\n| **2** (detailed) | Tool names with inputs + longer reasoning text |\n\n#### GitHub Workflow\n\nClaude Code already knows how to use `gh` CLI and `git`. Authenticate on your server with `gh auth login`, then work with repos conversationally:\n\n```\nYou: List my repos related to monitoring\nBot: [Claude runs gh repo list, shows results]\n\nYou: Clone the uptime one\nBot: [Claude runs gh repo clone, clones into workspace]\n\nYou: \u002Frepo\nBot: 📦 uptime-monitor\u002F  ◀\n     📁 other-project\u002F\n\nYou: Show me the open issues\nBot: [Claude runs gh issue list]\n\nYou: Create a fix branch and push it\nBot: [Claude creates branch, commits, pushes]\n```\n\nUse `\u002Frepo` to list cloned repos in your workspace, or `\u002Frepo \u003Cname>` to switch directories (sessions auto-resume).\n\n### Classic Mode\n\nSet `AGENTIC_MODE=false` to enable the full 13-command terminal-like interface with directory navigation, inline keyboards, quick actions, git integration, and session export.\n\n**Commands:** `\u002Fstart`, `\u002Fhelp`, `\u002Fnew`, `\u002Fcontinue`, `\u002Fend`, `\u002Fstatus`, `\u002Fcd`, `\u002Fls`, `\u002Fpwd`, `\u002Fprojects`, `\u002Fexport`, `\u002Factions`, `\u002Fgit`  \nIf `ENABLE_PROJECT_THREADS=true`: `\u002Fsync_threads`\n\n```\nYou: \u002Fcd my-web-app\nBot: Directory changed to my-web-app\u002F\n\nYou: \u002Fls\nBot: src\u002F  tests\u002F  package.json  README.md\n\nYou: \u002Factions\nBot: [Run Tests] [Install Deps] [Format Code] [Run Linter]\n```\n\n## Event-Driven Automation\n\nBeyond direct chat, the bot can respond to external triggers:\n\n- **Webhooks** -- Receive GitHub events (push, PR, issues) and route them through Claude for automated summaries or code review\n- **Scheduler** -- Run recurring Claude tasks on a cron schedule (e.g., daily code health checks)\n- **Notifications** -- Deliver agent responses to configured Telegram chats\n\nEnable with `ENABLE_API_SERVER=true` and `ENABLE_SCHEDULER=true`. See [docs\u002Fsetup.md](docs\u002Fsetup.md) for configuration.\n\n## Features\n\n### Working Features\n\n- Conversational agentic mode (default) with natural language interaction\n- Classic terminal-like mode with 13 commands and inline keyboards\n- Full Claude Code integration with SDK (primary) and CLI (fallback)\n- Automatic session persistence per user\u002Fproject directory\n- Multi-layer authentication (whitelist + optional token-based)\n- Rate limiting with token bucket algorithm\n- Directory sandboxing with path traversal prevention\n- File upload handling with archive extraction\n- Image\u002Fscreenshot upload with analysis\n- Voice message transcription (Mistral Voxtral \u002F OpenAI Whisper \u002F [local whisper.cpp](docs\u002Flocal-whisper-cpp.md))\n- Git integration with safe repository operations\n- Quick actions system with context-aware buttons\n- Session export in Markdown, HTML, and JSON formats\n- SQLite persistence with migrations\n- Usage and cost tracking\n- Audit logging and security event tracking\n- Event bus for decoupled message routing\n- Webhook API server (GitHub HMAC-SHA256, generic Bearer token auth)\n- Job scheduler with cron expressions and persistent storage\n- Notification service with per-chat rate limiting\n\n- Tunable verbose output showing Claude's tool usage and reasoning in real-time\n- Persistent typing indicator so users always know the bot is working\n- 16 configurable tools with allowlist\u002Fdisallowlist control (see [docs\u002Ftools.md](docs\u002Ftools.md))\n\n### Planned Enhancements\n\n- Plugin system for third-party extensions\n\n## Configuration\n\n### Required\n\n```bash\nTELEGRAM_BOT_TOKEN=...           # From @BotFather\nTELEGRAM_BOT_USERNAME=...        # Your bot's username\nAPPROVED_DIRECTORY=...           # Base directory for project access\nALLOWED_USERS=123456789          # Comma-separated Telegram user IDs\n```\n\n### Common Options\n\n```bash\n# Claude\nANTHROPIC_API_KEY=sk-ant-...     # API key (optional if using CLI auth)\nCLAUDE_MAX_COST_PER_USER=10.0    # Spending limit per user (USD)\nCLAUDE_TIMEOUT_SECONDS=300       # Operation timeout\n\n# Mode\nAGENTIC_MODE=true                # Agentic (default) or classic mode\nVERBOSE_LEVEL=1                  # 0=quiet, 1=normal (default), 2=detailed\n\n# Rate Limiting\nRATE_LIMIT_REQUESTS=10           # Requests per window\nRATE_LIMIT_WINDOW=60             # Window in seconds\n\n# Features (classic mode)\nENABLE_GIT_INTEGRATION=true\nENABLE_FILE_UPLOADS=true\nENABLE_QUICK_ACTIONS=true\n```\n\n### Agentic Platform\n\n```bash\n# Webhook API Server\nENABLE_API_SERVER=false          # Enable FastAPI webhook server\nAPI_SERVER_PORT=8080             # Server port\n\n# Webhook Authentication\nGITHUB_WEBHOOK_SECRET=...        # GitHub HMAC-SHA256 secret\nWEBHOOK_API_SECRET=...           # Bearer token for generic providers\n\n# Scheduler\nENABLE_SCHEDULER=false           # Enable cron job scheduler\n\n# Notifications\nNOTIFICATION_CHAT_IDS=123,456    # Default chat IDs for proactive notifications\n```\n\n### Project Threads Mode\n\n```bash\n# Enable strict topic routing by project\nENABLE_PROJECT_THREADS=true\n\n# Mode: private (default) or group\nPROJECT_THREADS_MODE=private\n\n# YAML registry file (see config\u002Fprojects.example.yaml)\nPROJECTS_CONFIG_PATH=config\u002Fprojects.yaml\n\n# Required only when PROJECT_THREADS_MODE=group\nPROJECT_THREADS_CHAT_ID=-1001234567890\n\n# Minimum delay (seconds) between Telegram API calls during topic sync\n# Set 0 to disable pacing\nPROJECT_THREADS_SYNC_ACTION_INTERVAL_SECONDS=1.1\n```\n\nIn strict mode, only `\u002Fstart` and `\u002Fsync_threads` work outside mapped project topics.\nIn private mode, `\u002Fstart` auto-syncs project topics for your private bot chat.\nTo use topics with your bot, enable them in BotFather:\n`Bot Settings -> Threaded mode`.\n\n> **Full reference:** See [docs\u002Fconfiguration.md](docs\u002Fconfiguration.md) and [`.env.example`](.env.example).\n\n### Finding Your Telegram User ID\n\nMessage [@userinfobot](https:\u002F\u002Ft.me\u002Fuserinfobot) on Telegram -- it will reply with your user ID number.\n\n## Troubleshooting\n\n**Bot doesn't respond:**\n- Check your `TELEGRAM_BOT_TOKEN` is correct\n- Verify your user ID is in `ALLOWED_USERS`\n- Ensure Claude Code CLI is installed and accessible\n- Check bot logs with `make run-debug`\n\n**Claude integration not working:**\n- SDK mode (default): Check `claude auth status` or verify `ANTHROPIC_API_KEY`\n- CLI mode: Verify `claude --version` and `claude auth status`\n- Check `CLAUDE_ALLOWED_TOOLS` includes necessary tools (see [docs\u002Ftools.md](docs\u002Ftools.md) for the full reference)\n\n**High usage costs:**\n- Adjust `CLAUDE_MAX_COST_PER_USER` to set spending limits\n- Monitor usage with `\u002Fstatus`\n- Use shorter, more focused requests\n\n## Security\n\nThis bot implements defense-in-depth security:\n\n- **Access Control** -- Whitelist-based user authentication\n- **Directory Isolation** -- Sandboxing to approved directories\n- **Rate Limiting** -- Request and cost-based limits\n- **Input Validation** -- Injection and path traversal protection\n- **Webhook Authentication** -- GitHub HMAC-SHA256 and Bearer token verification\n- **Audit Logging** -- Complete tracking of all user actions\n\nSee [SECURITY.md](SECURITY.md) for details.\n\n## Development\n\n```bash\nmake dev           # Install all dependencies\nmake test          # Run tests with coverage\nmake lint          # Black + isort + flake8 + mypy\nmake format        # Auto-format code\nmake run-debug     # Run with debug logging\nmake run-watch     # Run with auto-restart on code changes\n```\n\n> **Full documentation:** See the [docs index](docs\u002FREADME.md) for all guides and references.\n\n### Version Management\n\nThe version is defined once in `pyproject.toml` and read at runtime via `importlib.metadata`. To cut a release:\n\n```bash\nmake bump-patch    # 1.2.0 -> 1.2.1 (bug fixes)\nmake bump-minor    # 1.2.0 -> 1.3.0 (new features)\nmake bump-major    # 1.2.0 -> 2.0.0 (breaking changes)\n```\n\nEach command commits, tags, and pushes automatically, triggering CI tests and a GitHub Release with auto-generated notes.\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature\u002Famazing-feature`\n3. Make changes with tests: `make test && make lint`\n4. Submit a Pull Request\n\n**Code standards:** Python 3.11+, Black formatting (88 chars), type hints required, pytest with >85% coverage.\n\n## License\n\nMIT License -- see [LICENSE](LICENSE).\n\n## Star History\n\n[![Star History Chart](https:\u002F\u002Fapi.star-history.com\u002Fsvg?repos=RichardAtCT\u002Fclaude-code-telegram&type=Date)](https:\u002F\u002Fstar-history.com\u002F#RichardAtCT\u002Fclaude-code-telegram&Date)\n\n## Acknowledgments\n\n- [Claude](https:\u002F\u002Fclaude.ai) by Anthropic\n- [python-telegram-bot](https:\u002F\u002Fgithub.com\u002Fpython-telegram-bot\u002Fpython-telegram-bot)\n","Claude Code Telegram 是一个强大的Telegram机器人，它提供了远程访问Claude Code的功能，使开发者能够随时随地与他们的项目进行交互，并获得全面的人工智能辅助和会话持久化。其核心功能包括自然语言交流、跨对话上下文维护、通过任何设备上的Telegram进行代码操作以及接收来自Webhook、定时任务和CI\u002FCD事件的主动通知等。此外，该工具还内置了安全特性如认证机制、目录沙箱和审计日志记录。适合需要灵活工作环境或希望提高开发效率的程序员使用，在确保安全性的同时享受更加便捷的编码体验。",2,"2026-06-11 03:42:06","high_star"]