A Telegram bot that provides remote access to Claude Code CLI.

• Remote Claude Code access - Full Claude Code capabilities via Telegram
• Access control - User ID whitelist for security
• Session persistence - SQLite database stores conversation history
• Directory navigation - Browse and switch between projects
• Git integration - View status, diff, log, branches
• File uploads - Upload code files, images, and archives for analysis
• Quick actions - Context-aware buttons for common tasks (test, lint, build)
• Session export - Export conversations as Markdown, JSON, or HTML
• Project detection - Auto-detects Node.js, Python, Rust, Go projects

• Python 3.11+
• uv package manager
• Claude Code CLI installed and authenticated
• Telegram Bot Token (from @BotFather)

1. Install dependencies:

   uv sync

2. Configure environment:

   Edit .env:

   # Required
   TELEGRAM_TOKEN=your_bot_token_here
   ALLOWED_USERS=123456789  # comma-separated user IDs
   
   # Optional
   CLAUDE_WORKING_DIR=/path/to/projects  # base directory
   CLAUDE_MODEL=sonnet                    # or opus, haiku
   
   # Feature toggles (all default to true)
   ENABLE_GIT=true
   ENABLE_FILE_UPLOADS=true
   ENABLE_QUICK_ACTIONS=true

3. Find your Telegram user ID:

   Start the bot without ALLOWED_USERS set, then send it a message. It will reply with your user ID.

uv run python bot.py

Chat: Send any message to interact with Claude Code.

Files: Upload code files, images, or screenshots for analysis.

Archives: Upload ZIP/TAR files to extract and analyze projects.

Quick Actions: Use /actions for context-aware buttons:

• Python: uv sync, pytest, ruff
• Node.js: npm install, test, lint
• Rust: cargo build, test, clippy

• Denies all requests if ALLOWED_USERS is empty (secure by default)
• Path traversal protection - can only access within CLAUDE_WORKING_DIR
• Git commands restricted to read-only operations
• Archive extraction validates paths to prevent zip bombs

MIT