{"_id":"@a5c-ai/claude-code-telegram-bot","_rev":"6-5a13838cab0f720a590e796a3487ceda","name":"@a5c-ai/claude-code-telegram-bot","dist-tags":{"latest":"1.0.5"},"versions":{"1.0.0":{"name":"@a5c-ai/claude-code-telegram-bot","version":"1.0.0","keywords":["telegram","telegram-bot","claude","claude-code","anthropic","cli","bot","automation","remote","mobile","ai","llm"],"author":"","license":"MIT","_id":"@a5c-ai/claude-code-telegram-bot@1.0.0","maintainers":[{"name":"tmuskal","email":"tal@musk.al"},{"name":"benihak","email":"beni@a5c.ai"}],"homepage":"https://github.com/a5c-ai/claude-code-telegram-bot#readme","bugs":{"url":"https://github.com/a5c-ai/claude-code-telegram-bot/issues"},"bin":{"claude-code-telegram-bot":"dist/index.js"},"dist":{"shasum":"f4ad86dab7a119b02fcb1cb77af652cdd2d77b0b","tarball":"https://registry.npmjs.org/@a5c-ai/claude-code-telegram-bot/-/claude-code-telegram-bot-1.0.0.tgz","fileCount":103,"integrity":"sha512-JPEi/j3P2X5FSGL1xd2dDyXM0HUNZ78NvF++WHQRzsbRJHhAKljYt74+ozbL/HvhbgO+SAUga7d7wsdmzru7Jg==","signatures":[{"sig":"MEYCIQCOyAaqM0KjfKjV31u9uDyKqnVgIab27vFHcD1jwrnBgAIhAJLZ8rXHU5JQeustUdR8kBJ6Z3h8NvGmTYyQpfkuFA+L","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":695529},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"0b28cf80fbdd465127f0c5f0c7e4463d35f8cf12","scripts":{"dev":"ts-node --esm src/index.ts","test":"jest","build":"tsc","start":"node dist/index.js","test:watch":"jest --watch","test:coverage":"jest --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"tmuskal","email":"tal@musk.al"},"repository":{"url":"git+https://github.com/a5c-ai/claude-code-telegram-bot.git","type":"git"},"_npmVersion":"10.8.2","description":"A Telegram bot to remotely operate Claude Code CLI from anywhere","directories":{},"_nodeVersion":"18.20.8","dependencies":{"ulid":"^2.3.0","execa":"^8.0.1","dotenv":"^16.4.5","telegraf":"^4.16.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","ts-jest":"^29.1.2","ts-node":"^10.9.2","typescript":"^5.3.3","@types/jest":"^29.5.12","@types/node":"^20.11.20","@a5c-ai/babysitter-sdk":"^0.0.146"},"_npmOperationalInternal":{"tmp":"tmp/claude-code-telegram-bot_1.0.0_1770018887432_0.11066841856942533","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@a5c-ai/claude-code-telegram-bot","version":"1.0.1","keywords":["telegram","telegram-bot","claude","claude-code","anthropic","cli","bot","automation","remote","mobile","ai","llm"],"author":"","license":"MIT","_id":"@a5c-ai/claude-code-telegram-bot@1.0.1","maintainers":[{"name":"tmuskal","email":"tal@musk.al"},{"name":"benihak","email":"beni@a5c.ai"}],"homepage":"https://github.com/a5c-ai/claude-code-telegram-bot#readme","bugs":{"url":"https://github.com/a5c-ai/claude-code-telegram-bot/issues"},"bin":{"claude-code-telegram-bot":"dist/index.js"},"dist":{"shasum":"9a040d9b280573a283e0b02f1b137d2e595e0520","tarball":"https://registry.npmjs.org/@a5c-ai/claude-code-telegram-bot/-/claude-code-telegram-bot-1.0.1.tgz","fileCount":103,"integrity":"sha512-ZUD6eneB7SeCBSIDZhEZnbkeqQ568j+4HrVw9YyVi3onPVYgzLieBGqAztAfhvmax97Tv2uTslSw6kJ8FjNv6Q==","signatures":[{"sig":"MEUCIQCoja0LQhbnO4PxUqyRCab1ARmx2ie1eH0gOji7mG/ARQIgESlug8Tjl7dvuz+S59aLJPkz0bYlOTEnflL3D2aFhQs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":695529},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"9cf7488f593e39537e48f02d5efff3e40013c784","scripts":{"dev":"ts-node --esm src/index.ts","test":"jest","build":"tsc","start":"node dist/index.js","test:watch":"jest --watch","test:coverage":"jest --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"tmuskal","email":"tal@musk.al"},"repository":{"url":"git+https://github.com/a5c-ai/claude-code-telegram-bot.git","type":"git"},"_npmVersion":"10.8.2","description":"A Telegram bot to remotely operate Claude Code CLI from anywhere","directories":{},"_nodeVersion":"18.20.8","dependencies":{"ulid":"^2.3.0","execa":"^8.0.1","dotenv":"^16.4.5","telegraf":"^4.16.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","ts-jest":"^29.1.2","ts-node":"^10.9.2","typescript":"^5.3.3","@types/jest":"^29.5.12","@types/node":"^20.11.20","@a5c-ai/babysitter-sdk":"^0.0.146"},"_npmOperationalInternal":{"tmp":"tmp/claude-code-telegram-bot_1.0.1_1770020035477_0.5915518377772453","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@a5c-ai/claude-code-telegram-bot","version":"1.0.2","keywords":["telegram","telegram-bot","claude","claude-code","anthropic","cli","bot","automation","remote","mobile","ai","llm"],"author":"","license":"MIT","_id":"@a5c-ai/claude-code-telegram-bot@1.0.2","maintainers":[{"name":"tmuskal","email":"tal@musk.al"},{"name":"benihak","email":"beni@a5c.ai"}],"homepage":"https://github.com/a5c-ai/claude-code-telegram-bot#readme","bugs":{"url":"https://github.com/a5c-ai/claude-code-telegram-bot/issues"},"bin":{"claude-code-telegram-bot":"dist/index.js"},"dist":{"shasum":"b698b9bf830b19f5d078e387eb410b77224ede19","tarball":"https://registry.npmjs.org/@a5c-ai/claude-code-telegram-bot/-/claude-code-telegram-bot-1.0.2.tgz","fileCount":103,"integrity":"sha512-/ooivsxOUlPori8PaIh/hWYc0N2VCCXJBVdGGVt0rQlu/lZkHLT5B43hwSjc7y2mrkS25JN8/KYL9JE/h2dU3A==","signatures":[{"sig":"MEUCIQDpu6tidHAmRtC5ug4Z84WTsHXMIZL+J+ERCLGwtMt5WAIgGxj4UWWyZHfvfRBq7hY3YIqH40PZLaQngNRY7EWfwfI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":695529},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"7250562abff384fb10c54f978eddebb512c10ab3","scripts":{"dev":"ts-node --esm src/index.ts","test":"jest","build":"tsc","start":"node dist/index.js","test:watch":"jest --watch","test:coverage":"jest --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"tmuskal","email":"tal@musk.al"},"repository":{"url":"git+https://github.com/a5c-ai/claude-code-telegram-bot.git","type":"git"},"_npmVersion":"10.8.2","description":"A Telegram bot to remotely operate Claude Code CLI from anywhere","directories":{},"_nodeVersion":"18.20.8","dependencies":{"ulid":"^2.3.0","execa":"^8.0.1","dotenv":"^16.4.5","telegraf":"^4.16.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","ts-jest":"^29.1.2","ts-node":"^10.9.2","typescript":"^5.3.3","@types/jest":"^29.5.12","@types/node":"^20.11.20","@a5c-ai/babysitter-sdk":"^0.0.146"},"_npmOperationalInternal":{"tmp":"tmp/claude-code-telegram-bot_1.0.2_1770020282356_0.9557874528398487","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@a5c-ai/claude-code-telegram-bot","version":"1.0.3","keywords":["telegram","telegram-bot","claude","claude-code","anthropic","cli","bot","automation","remote","mobile","ai","llm"],"author":"","license":"MIT","_id":"@a5c-ai/claude-code-telegram-bot@1.0.3","maintainers":[{"name":"tmuskal","email":"tal@musk.al"},{"name":"benihak","email":"beni@a5c.ai"}],"homepage":"https://github.com/a5c-ai/claude-code-telegram-bot#readme","bugs":{"url":"https://github.com/a5c-ai/claude-code-telegram-bot/issues"},"bin":{"claude-code-telegram-bot":"dist/index.js"},"dist":{"shasum":"3009e3e87271e1b6caf4502d67dd06a15281fa6f","tarball":"https://registry.npmjs.org/@a5c-ai/claude-code-telegram-bot/-/claude-code-telegram-bot-1.0.3.tgz","fileCount":103,"integrity":"sha512-ix3SZjUZ5jvFKPK1tfQg0NHzxOYk0Fpl7BnhOlMby8GlSNiihpAscpzBhjsbPhhyKYuDlgU9q8w4orMi05Ieiw==","signatures":[{"sig":"MEUCIQC5B6r0GTIIOIr1l2CBgvQW7IEMfUmfkEp4BF69H/Zb6wIgHB4XZL+PayFf6CdFkDcI95PM7QD1EcHQR0J24C+tEdE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":695529},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"03667b7582baf145d782d37f1a04c47865adb0c6","scripts":{"dev":"ts-node --esm src/index.ts","test":"jest","build":"tsc","start":"node dist/index.js","test:watch":"jest --watch","test:coverage":"jest --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"tmuskal","email":"tal@musk.al"},"repository":{"url":"git+https://github.com/a5c-ai/claude-code-telegram-bot.git","type":"git"},"_npmVersion":"10.8.2","description":"A Telegram bot to remotely operate Claude Code CLI from anywhere","directories":{},"_nodeVersion":"18.20.8","dependencies":{"ulid":"^2.3.0","execa":"^8.0.1","dotenv":"^16.4.5","telegraf":"^4.16.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","ts-jest":"^29.1.2","ts-node":"^10.9.2","typescript":"^5.3.3","@types/jest":"^29.5.12","@types/node":"^20.11.20","@a5c-ai/babysitter-sdk":"^0.0.146"},"_npmOperationalInternal":{"tmp":"tmp/claude-code-telegram-bot_1.0.3_1770020494175_0.5738206911116168","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@a5c-ai/claude-code-telegram-bot","version":"1.0.4","keywords":["telegram","telegram-bot","claude","claude-code","anthropic","cli","bot","automation","remote","mobile","ai","llm"],"author":"","license":"MIT","_id":"@a5c-ai/claude-code-telegram-bot@1.0.4","maintainers":[{"name":"tmuskal","email":"tal@musk.al"},{"name":"benihak","email":"beni@a5c.ai"}],"homepage":"https://github.com/a5c-ai/claude-code-telegram-bot#readme","bugs":{"url":"https://github.com/a5c-ai/claude-code-telegram-bot/issues"},"bin":{"claude-code-telegram-bot":"dist/index.js"},"dist":{"shasum":"5d8b7c6369df9035e21cec6fff3c7ab0707d918f","tarball":"https://registry.npmjs.org/@a5c-ai/claude-code-telegram-bot/-/claude-code-telegram-bot-1.0.4.tgz","fileCount":103,"integrity":"sha512-gcYTS+5bll6EFUbByZ9CVFh8MPulDUNa4N6LZ0IsE32ApyBHGvFdMCe8iy9ZW2dRt4AoemVDu1OInnVDGKQM3A==","signatures":[{"sig":"MEUCIAoHje5ft9RLX8gwcj9N/6+X8O+ACrmAqR2WikQiUEqnAiEA5bTj70gaPRIKM85TSooZeeWHule5IXwuqiewD8UGF3A=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":695529},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"db0fa5158babf491dda2cf1570f920c3402ce425","scripts":{"dev":"ts-node --esm src/index.ts","test":"jest","build":"tsc","start":"node dist/index.js","test:watch":"jest --watch","test:coverage":"jest --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"tmuskal","email":"tal@musk.al"},"repository":{"url":"git+https://github.com/a5c-ai/claude-code-telegram-bot.git","type":"git"},"_npmVersion":"10.8.2","description":"A Telegram bot to remotely operate Claude Code CLI from anywhere","directories":{},"_nodeVersion":"18.20.8","dependencies":{"ulid":"^2.3.0","execa":"^8.0.1","dotenv":"^16.4.5","telegraf":"^4.16.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","ts-jest":"^29.1.2","ts-node":"^10.9.2","typescript":"^5.3.3","@types/jest":"^29.5.12","@types/node":"^20.11.20","@a5c-ai/babysitter-sdk":"^0.0.146"},"_npmOperationalInternal":{"tmp":"tmp/claude-code-telegram-bot_1.0.4_1770020665857_0.7982531931617929","host":"s3://npm-registry-packages-npm-production"}},"1.0.5":{"name":"@a5c-ai/claude-code-telegram-bot","version":"1.0.5","description":"A Telegram bot to remotely operate Claude Code CLI from anywhere","main":"dist/index.js","bin":{"claude-code-telegram-bot":"dist/index.js"},"type":"module","scripts":{"build":"tsc","start":"node dist/index.js","dev":"ts-node --esm src/index.ts","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","prepublishOnly":"npm run build"},"keywords":["telegram","telegram-bot","claude","claude-code","anthropic","cli","bot","automation","remote","mobile","ai","llm"],"author":"","license":"MIT","repository":{"type":"git","url":"git+https://github.com/a5c-ai/claude-code-telegram-bot.git"},"homepage":"https://github.com/a5c-ai/claude-code-telegram-bot#readme","bugs":{"url":"https://github.com/a5c-ai/claude-code-telegram-bot/issues"},"engines":{"node":">=18.0.0"},"publishConfig":{"access":"public"},"dependencies":{"dotenv":"^16.4.5","execa":"^8.0.1","telegraf":"^4.16.3","ulid":"^2.3.0"},"devDependencies":{"@a5c-ai/babysitter-sdk":"^0.0.146","@types/jest":"^29.5.12","@types/node":"^20.11.20","jest":"^29.7.0","ts-jest":"^29.1.2","ts-node":"^10.9.2","typescript":"^5.3.3"},"_id":"@a5c-ai/claude-code-telegram-bot@1.0.5","gitHead":"6bf9ffd28785d66c397c1ea50accdf99d8ff4f03","types":"./dist/index.d.ts","_nodeVersion":"18.20.8","_npmVersion":"10.8.2","dist":{"integrity":"sha512-y+am+ZaHYPZCXgKAW8DjPSpV3EbCvZFye5GVFVbLPp9/wgae/yxOJJ79jJJBEmS2k9b5UxRuRRYL012z34pfXg==","shasum":"8499e63d507f7e5cf922ceeef64850319a6b2148","tarball":"https://registry.npmjs.org/@a5c-ai/claude-code-telegram-bot/-/claude-code-telegram-bot-1.0.5.tgz","fileCount":103,"unpackedSize":695529,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC65XZf4sVPrUekXXXtCdfv3tcr3JK+psGaZeHE/gENwQIgV13kDaoVu1ooLYMqZMTPPxVBJH7Z2OcAbaiq8HnxrKc="}]},"_npmUser":{"name":"tmuskal","email":"tal@musk.al"},"directories":{},"maintainers":[{"name":"tmuskal","email":"tal@musk.al"},{"name":"benihak","email":"beni@a5c.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/claude-code-telegram-bot_1.0.5_1770021368222_0.21045950136577218"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-02T07:54:47.336Z","modified":"2026-02-02T08:36:08.544Z","1.0.0":"2026-02-02T07:54:47.602Z","1.0.1":"2026-02-02T08:13:55.640Z","1.0.2":"2026-02-02T08:18:02.488Z","1.0.3":"2026-02-02T08:21:34.315Z","1.0.4":"2026-02-02T08:24:25.994Z","1.0.5":"2026-02-02T08:36:08.391Z"},"bugs":{"url":"https://github.com/a5c-ai/claude-code-telegram-bot/issues"},"license":"MIT","homepage":"https://github.com/a5c-ai/claude-code-telegram-bot#readme","keywords":["telegram","telegram-bot","claude","claude-code","anthropic","cli","bot","automation","remote","mobile","ai","llm"],"repository":{"type":"git","url":"git+https://github.com/a5c-ai/claude-code-telegram-bot.git"},"description":"A Telegram bot to remotely operate Claude Code CLI from anywhere","maintainers":[{"name":"tmuskal","email":"tal@musk.al"},{"name":"benihak","email":"beni@a5c.ai"}],"readme":"# Claude Code Telegram Bot\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js 18+](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)\n[![Telegraf](https://img.shields.io/badge/Telegraf-4.16-blue.svg)](https://telegraf.js.org/)\n[![100% Built with Babysitter](https://img.shields.io/badge/100%25%20Built%20with-Babysitter%20%F0%9F%A7%99-blueviolet)](https://a5c.ai)\n\nA Telegram bot that bridges your mobile device with Anthropic's Claude Code CLI, enabling remote operation from anywhere. Create sessions, manage multiple projects, and interact with Claude's agentic coding capabilities directly through Telegram.\n\n## Demo\n\nhttps://github.com/user-attachments/assets/a8c14166-13f6-455b-b38a-aaa5ea499f80\n\n---\n\n## Features\n\n### Persistent Process Architecture\n\nThe bot uses a **single long-lived Claude CLI process per session** with bidirectional stdin/stdout streaming JSON communication. This architecture provides:\n\n- **Instant message handling** - No process spawn overhead per message\n- **Session continuity** - Maintains conversation context across all interactions\n- **Efficient resource usage** - Single process handles multiple message exchanges\n- **Native question/answer flow** - Responses to Claude's questions stream through stdin\n\n### Core Capabilities\n\n| Feature | Description |\n|---------|-------------|\n| **Remote Access** | Control Claude Code CLI from your phone or any device with Telegram |\n| **Session Management** | Create, list, switch, attach to, and close multiple Claude Code sessions |\n| **Interactive Q&A** | Receive Claude's questions as Telegram messages with inline response buttons |\n| **Streaming Responses** | Real-time draft message bubbles via Bot API 9.3 with configurable modes |\n| **Forum Topic Threading** | Bind sessions to specific forum threads for organized multi-project workflows |\n| **Multi-User Support** | Multiple authorized users can share the same bot instance |\n\n### Input Methods\n\n| Feature | Description |\n|---------|-------------|\n| **Text Messages** | Send prompts directly to Claude |\n| **Voice Messages** | Transcription via OpenAI Whisper API |\n| **File Uploads** | Documents, images, and code files sent to Claude |\n| **Inline Buttons** | Quick responses to Claude's questions |\n\n### Session Discovery\n\n| Feature | Description |\n|---------|-------------|\n| **Session Scanning** | Discover Claude sessions from `~/.claude/history.jsonl` |\n| **Session Attachment** | Attach to sessions started from terminal or other tools |\n| **Partial ID Matching** | Use just the first 8 characters of a session ID |\n\n---\n\n## Important Security Notice\n\n**This bot runs with `--dangerously-skip-permissions` enabled.**\n\nWith this flag, Claude will automatically read, write, delete files, run commands, and modify your system based on prompts without asking for confirmation.\n\n**Recommended for:**\n- Sandboxed development environments (Docker, VMs)\n- Disposable/ephemeral environments\n- Projects with version control where changes can be reverted\n\n**NOT recommended for:**\n- Production servers\n- Systems with sensitive data (credentials, keys, personal info)\n- Shared systems with other users' data\n- Environments without backups\n\n---\n\n## Prerequisites\n\nBefore installing, ensure you have:\n\n- **Node.js 18+** - [Download from nodejs.org](https://nodejs.org/)\n- **Claude Code CLI** - Installed and authenticated with your Anthropic account ([Installation Guide](https://docs.anthropic.com/en/docs/claude-code))\n- **Telegram Bot Token** - Create via [@BotFather](https://t.me/BotFather) (see instructions below)\n- **Your Telegram User ID** - For authorization (see instructions below)\n\n### Getting Your Bot Token\n\n1. Open Telegram and message [@BotFather](https://t.me/BotFather)\n2. Send `/newbot` command\n3. Follow the prompts to choose a name and username for your bot\n4. Copy the bot token provided (format: `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`)\n\n### Finding Your User ID\n\n1. Open Telegram and message [@userinfobot](https://t.me/userinfobot)\n2. The bot will reply with your user ID (a numeric value like `123456789`)\n3. Save this ID for the `ALLOWED_USER_IDS` configuration\n\n---\n\n## Installation\n\n### Quick Install (npm)\n\n```bash\nnpm install -g @a5c-ai/claude-code-telegram-bot\n```\n\nCreate a `.env` file with your configuration and run:\n\n```bash\nclaude-code-telegram-bot\n```\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/a5c-ai/claude-code-telegram-bot.git\ncd claude-code-telegram-bot\n\n# Install dependencies\nnpm install\n\n# Create environment configuration\ncp .env.example .env\n\n# Configure your .env file (see Environment Setup section below)\n\n# Build and start\nnpm run build\nnpm start\n```\n\n---\n\n## Configuration\n\n### Environment Setup\n\n1. **Copy the example environment file:**\n   ```bash\n   cp .env.example .env\n   ```\n\n2. **Edit `.env` with your configuration:**\n   ```bash\n   # Required: Your Telegram bot token from @BotFather\n   TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz\n\n   # Required: Comma-separated Telegram user IDs allowed to use the bot\n   ALLOWED_USER_IDS=123456789,987654321\n\n   # Optional: Default working directory for new sessions\n   DEFAULT_WORKING_DIR=/home/user/projects\n   ```\n\n3. **Save the file and start the bot.**\n\n### Required Settings\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `TELEGRAM_BOT_TOKEN` | Bot token from [@BotFather](https://t.me/BotFather) | `123456789:ABCdef...` |\n| `ALLOWED_USER_IDS` | Comma-separated list of authorized Telegram user IDs | `123456789,987654321` |\n\n### Optional Settings\n\n| Variable | Description | Default |\n|----------|-------------|--------|\n| `CLAUDE_CLI_PATH` | Absolute path to claude CLI executable | Auto-detected |\n| `DEFAULT_WORKING_DIR` | Default directory for new sessions | Current directory |\n| `LOG_LEVEL` | Logging level (`error`, `warn`, `info`, `debug`) | `info` |\n| `DEFAULT_VERBOSITY` | Output verbosity (`minimal`, `normal`, `verbose`) | `normal` |\n\n### Voice Transcription\n\n| Variable | Description | Default |\n|----------|-------------|--------|\n| `VOICE_ENABLED` | Enable voice message transcription | `false` |\n| `OPENAI_API_KEY` | OpenAI API key for Whisper transcription | - |\n\n### File Uploads\n\n| Variable | Description | Default |\n|----------|-------------|--------|\n| `FILE_UPLOAD_ENABLED` | Enable file upload support | `false` |\n| `MAX_FILE_SIZE_MB` | Maximum file size in megabytes | `10` |\n\n### Notification Defaults\n\n| Variable | Description | Default |\n|----------|-------------|--------|\n| `NOTIFICATION_DEFAULTS` | JSON object for default notification preferences | `{\"completion\":true,\"error\":true,\"warning\":true,\"progress\":false}` |\n\n### Streaming Configuration\n\n| Variable | Description | Default |\n|----------|-------------|--------|\n| `STREAMING_ENABLED` | Enable streaming draft messages | `true` |\n| `STREAMING_MODE` | Mode: `partial`, `block`, or `off` | `partial` |\n| `STREAMING_BLOCK_SIZE` | Characters per block in `block` mode | `50` |\n| `STREAMING_UPDATE_INTERVAL_MS` | Minimum interval between updates | `200` |\n\n### Threaded Mode (Forum Topics)\n\n| Variable | Description | Default |\n|----------|-------------|--------|\n| `THREADED_MODE_ENABLED` | Enable forum topic session binding | `false` |\n| `THREADED_AUTO_CREATE` | Auto-create topics for new sessions | `false` |\n| `THREADED_DEFAULT_TOPIC` | Prefix for auto-created topic names | `\"\"` |\n\n---\n\n## Commands\n\n### General\n\n| Command | Description |\n|---------|-------------|\n| `/start` | Welcome message and quick help |\n| `/help` | Show all available commands |\n\n### Session Management\n\n| Command | Description | Example |\n|---------|-------------|--------|\n| `/new <name> [dir]` | Create a new Claude Code session | `/new myproject /path/to/project` |\n| `/sessions` | List existing Claude sessions on system | `/sessions` |\n| `/attach <id> [dir]` | Attach to an existing Claude session | `/attach abc12345` |\n| `/list` | List all active bot sessions | `/list` |\n| `/switch <id>` | Switch to a different session | `/switch 01HGXK...` |\n| `/close [id]` | Close and terminate a session | `/close 01HGXK...` |\n| `/status` | Show current session details | `/status` |\n| `/cd <path>` | Change working directory of current session | `/cd /home/user/project` |\n\n### Session Control\n\n| Command | Description |\n|---------|-------------|\n| `/abort` | Send Ctrl+C to abort current operation |\n| `/escape` | Send ESC key to interrupt and allow new prompt |\n| `/kill` | Force kill the Claude process (hard stop) |\n\n### File Operations\n\n| Command | Description | Example |\n|---------|-------------|--------|\n| `/file <path> [--raw]` | View file contents or directory listing | `/file src/index.ts` |\n| `/pwd` | Show current working directory | `/pwd` |\n| `/tree [depth] [path]` | Show directory tree | `/tree 3 src/` |\n\n### Git Operations\n\n| Command | Description | Example |\n|---------|-------------|--------|\n| `/diff [--staged] [path]` | Show git diff | `/diff --staged` |\n| `/git [cmd] [args]` | Quick git operations | `/git status` |\n\n### Utility Commands\n\n| Command | Description | Example |\n|---------|-------------|--------|\n| `/log [n]` | View last n lines of output history | `/log 50` |\n| `/bookmark [action]` | Save/recall/list prompts | `/bookmark save test \"run tests\"` |\n| `/context` | Show context usage (tokens, percentage) | `/context` |\n| `/cost` | Show session cost information | `/cost` |\n| `/babysit` | Start Babysitter workflow orchestration | `/babysit` |\n\n### Settings\n\n| Command | Description | Example |\n|---------|-------------|--------|\n| `/voice [on\\|off]` | Toggle voice message transcription | `/voice on` |\n| `/notify <type> [on\\|off]` | Configure notifications | `/notify error off` |\n| `/verbosity [level]` | Set output verbosity | `/verbosity verbose` |\n| `/upload [on\\|off]` | Toggle file upload support | `/upload on` |\n| `/streaming [mode]` | Configure streaming output mode | `/streaming partial` |\n\n### Threaded Mode (Forum Topics)\n\n| Command | Description | Example |\n|---------|-------------|--------|\n| `/threads` | Configure threaded session mode | `/threads` |\n| `/topic` | Manage forum topics | `/topic create MySession` |\n| `/threadsession` | Show session bound to this thread | `/threadsession` |\n| `/threadsessions` | List all session-thread bindings | `/threadsessions` |\n| `/linksession <id>` | Link existing session to thread | `/linksession 01HGXK...` |\n| `/unlinksession` | Unlink session from thread | `/unlinksession` |\n\n---\n\n## Usage\n\n### Creating Your First Session\n\n```\n/new backend-api /home/user/projects/my-api\n```\n\nCreates a new session named \"backend-api\" in the specified directory. The session automatically becomes active.\n\n### Sending Prompts\n\nOnce a session is active, simply type your request:\n\n```\nCreate a REST endpoint for user authentication using JWT tokens\n```\n\nClaude will process your request and respond with its plan, code changes, and any questions.\n\n### Responding to Questions\n\nWhen Claude needs input, you'll receive a message with inline buttons:\n\n```\nClaude wants to create a new file:\nauth/middleware.ts\n\n[Yes, proceed] [No, skip] [Other...]\n```\n\nTap a button to respond, or select \"Other\" to type a custom answer.\n\n### Attaching to Existing Sessions\n\nDiscover and attach to Claude sessions started outside Telegram:\n\n```\n/sessions\n```\n\nShows recent sessions from `~/.claude/history.jsonl`:\n\n```\n📁 my-project\n   ID: `abc12345...`\n   2h ago\n   \"Last message preview...\"\n```\n\nAttach using partial ID:\n\n```\n/attach abc12345\n```\n\n### Using Voice Messages\n\nIf voice transcription is enabled:\n\n1. Enable voice: `/voice on`\n2. Send a voice message in Telegram\n3. The bot transcribes it via OpenAI Whisper\n4. Transcribed text is sent to Claude\n\n### Uploading Files\n\nIf file uploads are enabled:\n\n1. Enable uploads: `/upload on`\n2. Send a document or photo in Telegram\n3. Text files are embedded in the message; images/binaries are saved and path sent to Claude\n\n### Streaming Modes\n\nConfigure how Claude's responses appear:\n\n| Mode | Behavior |\n|------|----------|\n| `partial` | Real-time character-by-character streaming via draft bubbles |\n| `block` | Updates in chunks of configurable size |\n| `off` | Wait for complete response before showing |\n\n### Forum Topic Threading\n\nIn Telegram groups with forum topics enabled:\n\n1. Enable threaded mode: `/threads on`\n2. Create a topic: `/topic create ProjectX`\n3. Link a session: `/linksession <session-id>`\n4. Messages in that topic go to the linked session\n\n---\n\n## Architecture Overview\n\nThe bot uses a layered architecture with these primary components:\n\n| Component | Responsibility |\n|-----------|----------------|\n| **TelegramBot** | Main orchestrator - handles Telegram commands, user authorization, message routing |\n| **SessionManager** | Session lifecycle management with ULID-based IDs |\n| **ClaudeCodeProcess** | Persistent process wrapper with stdin/stdout streaming JSON |\n| **OutputParser** | Parses stream-json output, detects questions, emits typed events |\n| **StreamingService** | Bot API 9.3 draft message handling |\n| **DraftMessageHandler** | Draft bubble state management and throttling |\n| **ThreadManager** | Forum topic to session binding |\n| **TopicHandler** | Forum topic CRUD operations |\n| **ClaudeSessionScanner** | Scans `~/.claude/history.jsonl` for existing sessions |\n| **VoiceHandler** | Voice message transcription via OpenAI Whisper |\n| **FileHandler** | File upload validation and processing |\n| **NotificationManager** | Per-user notification preferences |\n| **CommandDefinitions** | Command metadata for Telegram menu registration |\n| **CommandRegistrationService** | Registers commands with Telegram Bot API |\n\n### Process Flow\n\n```\nUser Message → TelegramBot → SessionManager → ClaudeCodeProcess (stdin)\n                                                      ↓\n                                              Claude CLI (persistent)\n                                                      ↓\n                                              stdout (stream-json)\n                                                      ↓\n                                              OutputParser (events)\n                                                      ↓\n                              ┌─────────────────────────────────────┐\n                              ↓                    ↓                ↓\n                          'text'              'question'        'progress'\n                              ↓                    ↓                ↓\n                       StreamingService    Inline Keyboard    Status Updates\n                              ↓                    ↓                ↓\n                       Draft Bubble ──────→ Telegram Message ←─────┘\n```\n\n### Event Types\n\nOutputParser emits:\n- `started` - Claude session initialized\n- `thinking` - Claude started processing\n- `text` - Assistant text response\n- `question` - Interactive question (AskUserQuestion tool)\n- `tool_call` - Tool invocation\n- `progress` - Tool execution progress\n- `streaming_delta` - Partial text chunks (when streaming enabled)\n- `streaming_complete` - Stream finished\n\n---\n\n## Development\n\n### Running in Development Mode\n\n```bash\nnpm run dev\n```\n\n### Running Tests\n\n```bash\nnpm test                    # Run all tests\nnpm run test:watch          # Watch mode\nnpm run test:coverage       # Coverage report\n```\n\n### Project Structure\n\n```\nclaude-code-telegram/\n├── src/\n│   ├── index.ts                       # Entry point\n│   ├── bot/\n│   │   ├── TelegramBot.ts             # Main bot implementation\n│   │   └── commands/\n│   │       ├── CommandDefinitions.ts  # Command metadata\n│   │       └── CommandRegistrationService.ts\n│   ├── session/\n│   │   ├── SessionManager.ts          # Session lifecycle\n│   │   └── ClaudeCodeProcess.ts       # Persistent process wrapper\n│   ├── parser/\n│   │   └── OutputParser.ts            # Stream JSON parser\n│   ├── streaming/\n│   │   ├── StreamingService.ts        # Bot API 9.3 drafts\n│   │   └── DraftMessageHandler.ts     # Draft state management\n│   ├── threaded/\n│   │   ├── ThreadManager.ts           # Session-thread binding\n│   │   └── TopicHandler.ts            # Forum topic CRUD\n│   ├── utils/\n│   │   ├── ClaudeSessionScanner.ts    # Session discovery\n│   │   ├── VoiceHandler.ts            # Voice transcription\n│   │   └── FileHandler.ts             # File uploads\n│   ├── notifications/\n│   │   └── NotificationManager.ts     # Notification preferences\n│   ├── types/\n│   │   └── index.ts                   # TypeScript interfaces\n│   └── config/\n│       └── index.ts                   # Configuration management\n├── tests/\n├── package.json\n├── tsconfig.json\n└── .env.example\n```\n\n---\n\n## Troubleshooting\n\n### Bot not responding\n\n1. Verify your Telegram user ID is in `ALLOWED_USER_IDS`\n2. Ensure `TELEGRAM_BOT_TOKEN` is correct\n3. Run with `LOG_LEVEL=debug` for verbose output\n4. Check for \"Telegram bot started successfully\" in logs\n\n### \"No active session\" error\n\nCreate a session first:\n```\n/new my-session /path/to/project\n```\n\n### Claude CLI not found\n\n1. Verify installation: `claude --version`\n2. Check PATH or set `CLAUDE_CLI_PATH=/full/path/to/claude` in `.env`\n\nCommon paths:\n- macOS (Apple Silicon): `/opt/homebrew/bin/claude`\n- macOS (Intel) / Linux: `/usr/local/bin/claude`\n- Linux system-wide: `/usr/bin/claude`\n\n### Claude not responding to prompts\n\n1. Check session status: `/status`\n2. Verify working directory exists and is accessible\n3. Test Claude CLI manually: `claude --version`\n4. Abort stuck process: `/abort` or `/kill`\n\n### /sessions shows no sessions\n\n1. Check Claude history file exists: `ls ~/.claude/history.jsonl`\n2. Verify Claude has been used at least once\n3. Check file permissions on `~/.claude/`\n\n### /attach fails to find session\n\n1. Use partial ID (first 8 characters)\n2. Run `/sessions` to verify session exists\n3. Specify working directory if original moved: `/attach abc12345 /new/path`\n\n### Streaming not working\n\n1. Verify `STREAMING_ENABLED=true`\n2. Check `STREAMING_MODE` is not `off`\n3. Bot API 9.3 draft messages require recent Telegram client\n\n### Messages getting truncated\n\nTelegram limits messages to 4096 characters. Long responses are automatically truncated with \"...(truncated)\" indicator.\n\n---\n\n## Limitations\n\n| Limitation | Details |\n|------------|--------|\n| **Message size** | Telegram 4096 character limit per message |\n| **File uploads** | 10MB default (configurable) |\n| **Input length** | 10KB maximum to prevent abuse |\n| **Session persistence** | Bot sessions lost on restart (Claude history preserved in `~/.claude/`) |\n| **Windows support** | Not tested; may require path adjustments |\n\n---\n\n## Security\n\n### Authorization\n\n- Whitelist-based access via `ALLOWED_USER_IDS`\n- Per-message verification against whitelist\n- Unauthorized access attempts are logged\n\n### Process Isolation\n\n- Child processes spawned with sanitized environment\n- `CLAUDE_SESSION_ID`, `CLAUDECODE`, `CLAUDE_CODE_ENTRYPOINT` stripped\n\n### Input Validation\n\n- Maximum 10,240 characters per message\n- Rate limiting: minimum 1 second between messages\n- Maximum 50 queued messages\n- File size limits and extension whitelist\n- Path traversal protection\n\n### Best Practices\n\n1. Restrict `ALLOWED_USER_IDS` to trusted users only\n2. Create a dedicated bot specifically for this purpose\n3. Run in sandboxed environment (Docker, VM)\n4. Keep dependencies updated\n5. Monitor sessions regularly with `/list`\n\n---\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Write tests for new functionality\n4. Ensure all tests pass: `npm test`\n5. Submit a pull request with clear description\n\n---\n\n## Contributors\n\n<a href=\"https://github.com/a5c-ai/claude-code-telegram-bot/graphs/contributors\">\n  <img src=\"https://contrib.rocks/image?repo=a5c-ai/claude-code-telegram-bot\" />\n</a>\n\n---\n\n## Star History\n\n<a href=\"https://star-history.com/#a5c-ai/claude-code-telegram-bot&Date\">\n <picture>\n   <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/svg?repos=a5c-ai/claude-code-telegram-bot&type=Date&theme=dark\" />\n   <source media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/svg?repos=a5c-ai/claude-code-telegram-bot&type=Date\" />\n   <img alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=a5c-ai/claude-code-telegram-bot&type=Date\" />\n </picture>\n</a>\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n**Note:** This project is not officially affiliated with Anthropic. Claude Code is a product of Anthropic.\n\n---\n\n[![100% Built with Babysitter](https://img.shields.io/badge/100%25%20Built%20with-Babysitter%20%F0%9F%A7%99-blueviolet)](https://a5c.ai) **100% Built using [Babysitter](https://github.com/a5c-ai/babysitter) by [a5c.ai](https://a5c.ai)** - AI-powered development orchestration.","readmeFilename":"README.md"}