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

demo.mp4

Features

Persistent Process Architecture

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

Core Capabilities

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

Input Methods

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

Session Discovery

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)

Getting Your Bot Token

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

Finding Your User ID

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

Installation

Quick Install (npm)

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

Create a .env file with your configuration and run:

claude-code-telegram-bot

From Source

# 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

Environment Setup

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

Edit .env with your configuration:

# 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

Save the file and start the bot.

Required Settings

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`

Optional Settings

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`

Voice Transcription

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

File Uploads

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

Notification Defaults

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

Streaming Configuration

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`

Threaded Mode (Forum Topics)

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

General

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

Session Management

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

Session Control

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)

File Operations

Command	Description	Example
`/file <path> [--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/`

Git Operations

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

Utility Commands

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`

Settings

Command	Description	Example
`/voice [on\|off]`	Toggle voice message transcription	`/voice on`
`/notify <type> [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`

Threaded Mode (Forum Topics)

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 <id>`	Link existing session to thread	`/linksession 01HGXK...`
`/unlinksession`	Unlink session from thread	`/unlinksession`

Usage

Creating Your First Session

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

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

Sending Prompts

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.

Responding to Questions

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.

Attaching to Existing Sessions

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

Using Voice Messages

If voice transcription is enabled:

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

Uploading Files

If file uploads are enabled:

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

Streaming Modes

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

Forum Topic Threading

In Telegram groups with forum topics enabled:

Enable threaded mode: /threads on
Create a topic: /topic create ProjectX
Link a session: /linksession <session-id>
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

Process Flow

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 ←─────┘

Event Types

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

Running in Development Mode

npm run dev

Running Tests

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

Project Structure

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

Bot not responding

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

"No active session" error

Create a session first:

/new my-session /path/to/project

Claude CLI not found

Verify installation: claude --version
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

Claude not responding to prompts

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

/sessions shows no sessions

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

/attach fails to find session

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

Streaming not working

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

Messages getting truncated

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

Authorization

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

Process Isolation

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

Input Validation

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

Best Practices

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

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Write tests for new functionality
Ensure all tests pass: npm test
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.

Name		Name	Last commit message	Last commit date
Latest commit History 58 Commits
.claude		.claude
.github/workflows		.github/workflows
docs		docs
remotion-video		remotion-video
src		src
tests		tests
website		website
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
QUICKSTART.md		QUICKSTART.md
README.md		README.md
demo.mp4		demo.mp4
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Claude Code Telegram Bot

Demo

Features

Persistent Process Architecture

Core Capabilities

Input Methods

Session Discovery

Important Security Notice

Prerequisites

Getting Your Bot Token

Finding Your User ID

Installation

Quick Install (npm)

From Source

Configuration

Environment Setup

Required Settings

Optional Settings

Voice Transcription

File Uploads

Notification Defaults

Streaming Configuration

Threaded Mode (Forum Topics)

Commands

General

Session Management

Session Control

File Operations

Git Operations

Utility Commands

Settings

Threaded Mode (Forum Topics)

Usage

Creating Your First Session

Sending Prompts

Responding to Questions

Attaching to Existing Sessions

Using Voice Messages

Uploading Files

Streaming Modes

Forum Topic Threading

Architecture Overview

Process Flow

Event Types

Development

Running in Development Mode

Running Tests

Project Structure

Troubleshooting

Bot not responding

"No active session" error

Claude CLI not found

Claude not responding to prompts

/sessions shows no sessions

/attach fails to find session

Streaming not working

Messages getting truncated

Limitations

Security

Authorization

Process Isolation

Input Validation

Best Practices

Contributing

Contributors

Star History

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Packages