Claude Code Telegram Bot


A 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.

Demo

https://github.com/user-attachments/assets/a8c14166-13f6-455b-b38a-aaa5ea499f80

---

Features

$3

The bot uses a single long-lived Claude CLI process per session with bidirectional stdin/stdout streaming JSON communication. This architecture provides:

- Instant message handling - No process spawn overhead per message
- Session continuity - Maintains conversation context across all interactions
- Efficient resource usage - Single process handles multiple message exchanges
- Native question/answer flow - Responses to Claude's questions stream through stdin

$3

| Feature | Description |
|---------|-------------|
| Remote Access | Control Claude Code CLI from your phone or any device with Telegram |
| Session Management | Create, list, switch, attach to, and close multiple Claude Code sessions |
| Interactive Q&A | Receive Claude's questions as Telegram messages with inline response buttons |
| Streaming Responses | Real-time draft message bubbles via Bot API 9.3 with configurable modes |
| Forum Topic Threading | Bind sessions to specific forum threads for organized multi-project workflows |
| Multi-User Support | Multiple authorized users can share the same bot instance |

$3

| Feature | Description |
|---------|-------------|
| Text Messages | Send prompts directly to Claude |
| Voice Messages | Transcription via OpenAI Whisper API |
| File Uploads | Documents, images, and code files sent to Claude |
| Inline Buttons | Quick responses to Claude's questions |

$3

| Feature | Description |
|---------|-------------|
| Session Scanning | Discover Claude sessions from ~/.claude/history.jsonl |
| Session Attachment | Attach to sessions started from terminal or other tools |
| Partial ID Matching | Use just the first 8 characters of a session ID |

---

Important Security Notice

This bot runs with --dangerously-skip-permissions enabled.

With this flag, Claude will automatically read, write, delete files, run commands, and modify your system based on prompts without asking for confirmation.

Recommended for:
- Sandboxed development environments (Docker, VMs)
- Disposable/ephemeral environments
- Projects with version control where changes can be reverted

NOT recommended for:
- Production servers
- Systems with sensitive data (credentials, keys, personal info)
- Shared systems with other users' data
- Environments without backups

---

Prerequisites

Before installing, ensure you have:

- Node.js 18+ - Download from nodejs.org
- Claude Code CLI - Installed and authenticated with your Anthropic account (Installation Guide)
- Telegram Bot Token - Create via @BotFather (see instructions below)
- Your Telegram User ID - For authorization (see instructions below)

$3

1. Open Telegram and message @BotFather
2. Send /newbot command
3. Follow the prompts to choose a name and username for your bot
4. Copy the bot token provided (format: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

$3

1. Open Telegram and message @userinfobot
2. The bot will reply with your user ID (a numeric value like 123456789)
3. Save this ID for the ALLOWED_USER_IDS configuration

---

Installation

$3

``bash
npm install -g @a5c-ai/claude-code-telegram-bot
`

Create a .env file with your configuration and run:

`bash
claude-code-telegram-bot
`

$3

`bash


Clone the repository

git clone https://github.com/a5c-ai/claude-code-telegram-bot.git
cd claude-code-telegram-bot

Install dependencies

npm install

Create environment configuration

cp .env.example .env

Configure your .env file (see Environment Setup section below)

Build and start

npm run build
npm start
`

---

Configuration

$3

1. Copy the example environment file:
`bash
cp .env.example .env
`

2. Edit .env with your configuration:
`bash
# Required: Your Telegram bot token from @BotFather
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

# Required: Comma-separated Telegram user IDs allowed to use the bot
ALLOWED_USER_IDS=123456789,987654321

# Optional: Default working directory for new sessions
DEFAULT_WORKING_DIR=/home/user/projects
`

3. Save the file and start the bot.

$3

| Variable | Description | Example |
|----------|-------------|---------|
| TELEGRAM_BOT_TOKEN | Bot token from @BotFather | 123456789:ABCdef... |
| ALLOWED_USER_IDS | Comma-separated list of authorized Telegram user IDs | 123456789,987654321 |

$3

| Variable | Description | Default |
|----------|-------------|--------|
| CLAUDE_CLI_PATH | Absolute path to claude CLI executable | Auto-detected |
| DEFAULT_WORKING_DIR | Default directory for new sessions | Current directory |
| LOG_LEVEL | Logging level (error, warn, info, debug) | info |
| DEFAULT_VERBOSITY | Output verbosity (minimal, normal, verbose) | normal |

$3

| Variable | Description | Default |
|----------|-------------|--------|
| VOICE_ENABLED | Enable voice message transcription | false |
| OPENAI_API_KEY | OpenAI API key for Whisper transcription | - |

$3

| Variable | Description | Default |
|----------|-------------|--------|
| FILE_UPLOAD_ENABLED | Enable file upload support | false |
| MAX_FILE_SIZE_MB | Maximum file size in megabytes | 10 |

$3

| Variable | Description | Default |
|----------|-------------|--------|
| NOTIFICATION_DEFAULTS | JSON object for default notification preferences | {"completion":true,"error":true,"warning":true,"progress":false} |

$3

| Variable | Description | Default |
|----------|-------------|--------|
| STREAMING_ENABLED | Enable streaming draft messages | true |
| STREAMING_MODE | Mode: partial, block, or off | partial |
| STREAMING_BLOCK_SIZE | Characters per block in block mode | 50 |
| STREAMING_UPDATE_INTERVAL_MS | Minimum interval between updates | 200 |

$3

| Variable | Description | Default |
|----------|-------------|--------|
| THREADED_MODE_ENABLED | Enable forum topic session binding | false |
| THREADED_AUTO_CREATE | Auto-create topics for new sessions | false |
| THREADED_DEFAULT_TOPIC | Prefix for auto-created topic names | "" |

---

Commands

$3

| Command | Description |
|---------|-------------|
| /start | Welcome message and quick help |
| /help | Show all available commands |

$3

| Command | Description | Example |
|---------|-------------|--------|
| /new [dir] | Create a new Claude Code session | /new myproject /path/to/project |
| /sessions | List existing Claude sessions on system | /sessions |
| /attach [dir] | Attach to an existing Claude session | /attach abc12345 |
| /list | List all active bot sessions | /list |
| /switch | Switch to a different session | /switch 01HGXK... |
| /close [id] | Close and terminate a session | /close 01HGXK... |
| /status | Show current session details | /status |
| /cd | Change working directory of current session | /cd /home/user/project |

$3

| Command | Description |
|---------|-------------|
| /abort | Send Ctrl+C to abort current operation |
| /escape | Send ESC key to interrupt and allow new prompt |
| /kill | Force kill the Claude process (hard stop) |

$3

| Command | Description | Example |
|---------|-------------|--------|
| /file [--raw] | View file contents or directory listing | /file src/index.ts |
| /pwd | Show current working directory | /pwd |
| /tree [depth] [path] | Show directory tree | /tree 3 src/ |

$3

| Command | Description | Example |
|---------|-------------|--------|
| /diff [--staged] [path] | Show git diff | /diff --staged |
| /git [cmd] [args] | Quick git operations | /git status |

$3

| Command | Description | Example |
|---------|-------------|--------|
| /log [n] | View last n lines of output history | /log 50 |
| /bookmark [action] | Save/recall/list prompts | /bookmark save test "run tests" |
| /context | Show context usage (tokens, percentage) | /context |
| /cost | Show session cost information | /cost |
| /babysit | Start Babysitter workflow orchestration | /babysit |

$3

| Command | Description | Example |
|---------|-------------|--------|
| /voice [on\|off] | Toggle voice message transcription | /voice on |
| /notify [on\|off] | Configure notifications | /notify error off |
| /verbosity [level] | Set output verbosity | /verbosity verbose |
| /upload [on\|off] | Toggle file upload support | /upload on |
| /streaming [mode] | Configure streaming output mode | /streaming partial |

$3

| Command | Description | Example |
|---------|-------------|--------|
| /threads | Configure threaded session mode | /threads |
| /topic | Manage forum topics | /topic create MySession |
| /threadsession | Show session bound to this thread | /threadsession |
| /threadsessions | List all session-thread bindings | /threadsessions |
| /linksession | Link existing session to thread | /linksession 01HGXK... |
| /unlinksession | Unlink session from thread | /unlinksession |

---

Usage

$3

`
/new backend-api /home/user/projects/my-api
`

Creates a new session named "backend-api" in the specified directory. The session automatically becomes active.

$3

Once a session is active, simply type your request:

`
Create a REST endpoint for user authentication using JWT tokens
`

Claude will process your request and respond with its plan, code changes, and any questions.

$3

When Claude needs input, you'll receive a message with inline buttons:

`
Claude wants to create a new file:
auth/middleware.ts

[Yes, proceed] [No, skip] [Other...]
`

Tap a button to respond, or select "Other" to type a custom answer.

$3

Discover and attach to Claude sessions started outside Telegram:

`
/sessions
`

Shows recent sessions from ~/.claude/history.jsonl:

`
📁 my-project
ID: abc12345...
2h ago
"Last message preview..."
`

Attach using partial ID:

`
/attach abc12345
`

$3

If voice transcription is enabled:

1. Enable voice: /voice on
2. Send a voice message in Telegram
3. The bot transcribes it via OpenAI Whisper
4. Transcribed text is sent to Claude

$3

If file uploads are enabled:

1. Enable uploads: /upload on
2. Send a document or photo in Telegram
3. Text files are embedded in the message; images/binaries are saved and path sent to Claude

$3

Configure how Claude's responses appear:

| Mode | Behavior |
|------|----------|
| partial | Real-time character-by-character streaming via draft bubbles |
| block | Updates in chunks of configurable size |
| off | Wait for complete response before showing |

$3

In Telegram groups with forum topics enabled:

1. Enable threaded mode: /threads on
2. Create a topic: /topic create ProjectX
3. Link a session: /linksession
4. Messages in that topic go to the linked session

---

Architecture Overview

The bot uses a layered architecture with these primary components:

| Component | Responsibility |
|-----------|----------------|
| TelegramBot | Main orchestrator - handles Telegram commands, user authorization, message routing |
| SessionManager | Session lifecycle management with ULID-based IDs |
| ClaudeCodeProcess | Persistent process wrapper with stdin/stdout streaming JSON |
| OutputParser | Parses stream-json output, detects questions, emits typed events |
| StreamingService | Bot API 9.3 draft message handling |
| DraftMessageHandler | Draft bubble state management and throttling |
| ThreadManager | Forum topic to session binding |
| TopicHandler | Forum topic CRUD operations |
| ClaudeSessionScanner | Scans ~/.claude/history.jsonl for existing sessions |
| VoiceHandler | Voice message transcription via OpenAI Whisper |
| FileHandler | File upload validation and processing |
| NotificationManager | Per-user notification preferences |
| CommandDefinitions | Command metadata for Telegram menu registration |
| CommandRegistrationService | Registers commands with Telegram Bot API |

$3

`
User Message → TelegramBot → SessionManager → ClaudeCodeProcess (stdin)
↓
Claude CLI (persistent)
↓
stdout (stream-json)
↓
OutputParser (events)
↓
┌─────────────────────────────────────┐
↓ ↓ ↓
'text' 'question' 'progress'
↓ ↓ ↓
StreamingService Inline Keyboard Status Updates
↓ ↓ ↓
Draft Bubble ──────→ Telegram Message ←─────┘
`

$3

OutputParser emits:
- started - Claude session initialized
- thinking - Claude started processing
- text - Assistant text response
- question - Interactive question (AskUserQuestion tool)
- tool_call - Tool invocation
- progress - Tool execution progress
- streaming_delta - Partial text chunks (when streaming enabled)
- streaming_complete - Stream finished

---

Development

$3

`bash
npm run dev
`

$3

`bash
npm test # Run all tests
npm run test:watch # Watch mode
npm run test:coverage # Coverage report
`

$3

`
claude-code-telegram/
├── src/
│ ├── index.ts # Entry point
│ ├── bot/
│ │ ├── TelegramBot.ts # Main bot implementation
│ │ └── commands/
│ │ ├── CommandDefinitions.ts # Command metadata
│ │ └── CommandRegistrationService.ts
│ ├── session/
│ │ ├── SessionManager.ts # Session lifecycle
│ │ └── ClaudeCodeProcess.ts # Persistent process wrapper
│ ├── parser/
│ │ └── OutputParser.ts # Stream JSON parser
│ ├── streaming/
│ │ ├── StreamingService.ts # Bot API 9.3 drafts
│ │ └── DraftMessageHandler.ts # Draft state management
│ ├── threaded/
│ │ ├── ThreadManager.ts # Session-thread binding
│ │ └── TopicHandler.ts # Forum topic CRUD
│ ├── utils/
│ │ ├── ClaudeSessionScanner.ts # Session discovery
│ │ ├── VoiceHandler.ts # Voice transcription
│ │ └── FileHandler.ts # File uploads
│ ├── notifications/
│ │ └── NotificationManager.ts # Notification preferences
│ ├── types/
│ │ └── index.ts # TypeScript interfaces
│ └── config/
│ └── index.ts # Configuration management
├── tests/
├── package.json
├── tsconfig.json
└── .env.example
`

---

Troubleshooting

$3

1. Verify your Telegram user ID is in ALLOWED_USER_IDS
2. Ensure TELEGRAM_BOT_TOKEN is correct
3. Run with LOG_LEVEL=debug for verbose output
4. Check for "Telegram bot started successfully" in logs

$3

Create a session first:
`
/new my-session /path/to/project
`

$3

1. Verify installation: claude --version
2. Check PATH or set CLAUDE_CLI_PATH=/full/path/to/claude in .env

Common paths:
- macOS (Apple Silicon): /opt/homebrew/bin/claude
- macOS (Intel) / Linux: /usr/local/bin/claude
- Linux system-wide: /usr/bin/claude

$3

1. Check session status: /status
2. Verify working directory exists and is accessible
3. Test Claude CLI manually: claude --version
4. Abort stuck process: /abort or /kill

$3

1. Check Claude history file exists: ls ~/.claude/history.jsonl
2. Verify Claude has been used at least once
3. Check file permissions on ~/.claude/

$3

1. Use partial ID (first 8 characters)
2. Run /sessions to verify session exists
3. Specify working directory if original moved: /attach abc12345 /new/path

$3

1. Verify STREAMING_ENABLED=true
2. Check STREAMING_MODE is not off
3. Bot API 9.3 draft messages require recent Telegram client

$3

Telegram limits messages to 4096 characters. Long responses are automatically truncated with "...(truncated)" indicator.

---

Limitations

| Limitation | Details |
|------------|--------|
| Message size | Telegram 4096 character limit per message |
| File uploads | 10MB default (configurable) |
| Input length | 10KB maximum to prevent abuse |
| Session persistence | Bot sessions lost on restart (Claude history preserved in ~/.claude/) |
| Windows support | Not tested; may require path adjustments |

---

Security

$3

- Whitelist-based access via ALLOWED_USER_IDS
- Per-message verification against whitelist
- Unauthorized access attempts are logged

$3

- Child processes spawned with sanitized environment
- CLAUDE_SESSION_ID, CLAUDECODE, CLAUDE_CODE_ENTRYPOINT stripped

$3

- Maximum 10,240 characters per message
- Rate limiting: minimum 1 second between messages
- Maximum 50 queued messages
- File size limits and extension whitelist
- Path traversal protection

$3

1. Restrict ALLOWED_USER_IDS to trusted users only
2. Create a dedicated bot specifically for this purpose
3. Run in sandboxed environment (Docker, VM)
4. Keep dependencies updated
5. Monitor sessions regularly with /list

---

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Ensure all tests pass: npm test`
5. Submit a pull request with clear description

---

Contributors

---

Star History

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Note: This project is not officially affiliated with Anthropic. Claude Code is a product of Anthropic.

---

 100% Built using Babysitter by a5c.ai - AI-powered development orchestration.