Claude Telegram Bot

# Claude Telegram Bot

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Bun](https://img.shields.io/badge/Bun-1.0+-black.svg)](https://bun.sh/)

**Turn [Claude Code](https://claude.com/product/claude-code) into your personal assistant, accessible from anywhere via Telegram.**

Send text, voice, photos, and documents. See responses and tools usage in real-time.

![Demo](assets/demo.gif)

## Claude Code as a Personal Assistant

I've started using Claude Code as a personal assistant, and I've built this bot so I can access it from anywhere.

In fact, while Claude Code is described as a powerful AI **coding agent**, it's actually a very capable **general-purpose agent** too when given the right instructions, context, and tools.

To achieve this, I set up a folder with a CLAUDE.md that teaches Claude about me (my preferences, where my notes live, my workflows), has a set of tools and scripts based on my needs, and pointed this bot at that folder.

→ **[📄 See the Personal Assistant Guide](docs/personal-assistant-guide.md)** for detailed setup and examples.

## Bot Features

- 💬 **Text**: Ask questions, give instructions, have conversations
- 🎤 **Voice**: Speak naturally - transcribed via OpenAI and processed by Claude
- 📸 **Photos**: Send screenshots, documents, or anything visual for analysis
- 📄 **Documents**: PDFs, text files, and archives (ZIP, TAR) are extracted and analyzed
- 🔄 **Session persistence**: Conversations continue across messages
- 📨 **Message queuing**: Send multiple messages while Claude works - they queue up automatically. Prefix with `!` or use `/stop` to interrupt and send immediately
- 🧠 **Extended thinking**: Trigger Claude's reasoning by using words like "think" or "reason" - you'll see its thought process as it works (configurable via `THINKING_TRIGGER_KEYWORDS`)
- 🔘 **Interactive buttons**: Claude can present options as tappable inline buttons via the built-in `ask_user` MCP tool

## Quick Start

```bash
git clone https://github.com/linuz90/claude-telegram-bot?tab=readme-ov-file
cd claude-telegram-bot-ts

cp .env.example .env
# Edit .env with your credentials

bun install
bun run src/index.ts
```

### Prerequisites

- **Bun 1.0+** - [Install Bun](https://bun.sh/)
- **Claude Agent SDK** - `@anthropic-ai/claude-agent-sdk` (installed via bun install)
- **Telegram Bot Token** from [@BotFather](https://t.me/BotFather)
- **OpenAI API Key** (optional, for voice transcription)

### Claude Authentication

The bot uses the `@anthropic-ai/claude-agent-sdk` which supports two authentication methods:

| Method                     | Best For                                | Setup                             |
| -------------------------- | --------------------------------------- | --------------------------------- |
| **CLI Auth** (recommended) | High usage, cost-effective              | Run `claude` once to authenticate |
| **API Key**                | CI/CD, environments without Claude Code | Set `ANTHROPIC_API_KEY` in `.env` |

**CLI Auth** (recommended): The SDK automatically uses your Claude Code login. Just ensure you've run `claude` at least once and authenticated. This uses your Claude Code subscription which is much more cost-effective for heavy usage.

**API Key**: For environments where Claude Code isn't installed. Get a key from [console.anthropic.com](https://console.anthropic.com/) and add to `.env`:

```bash
ANTHROPIC_API_KEY=sk-ant-api03-...
```

Note: API usage is billed per token and can get expensive quickly for heavy use.

## Configuration

### 1. Create Your Bot

1. Open [@BotFather](https://t.me/BotFather) on Telegram
2. Send `/newbot` and follow the prompts to create your bot
3. Copy the token (looks like `1234567890:ABC-DEF...`)

Then send `/setcommands` to BotFather and paste this:

```
start - Show status and user ID
new - Start a fresh session
resume - Pick from recent sessions to resume
stop - Interrupt current query
status - Check what Claude is doing
restart - Restart the bot
```

### 2. Configure Environment

Create `.env` with your settings:

```bash
# Required
TELEGRAM_BOT_TOKEN=1234567890:ABC-DEF...   # From @BotFather
TELEGRAM_ALLOWED_USERS=123456789           # Your Telegram user ID

# Recommended
CLAUDE_WORKING_DIR=/path/to/your/folder    # Where Claude runs (loads CLAUDE.md, skills, MCP)
OPENAI_API_KEY=sk-...                      # For voice transcription
```

**Finding your Telegram user ID:** Message [@userinfobot](https://t.me/userinfobot) on Telegram.

**File access paths:** By default, Claude can access:

- `CLAUDE_WORKING_DIR` (or home directory if not set)
- `~/Documents`, `~/Downloads`, `~/Desktop`
- `~/.claude` (for Claude Code plans and settings)

To customize, set `ALLOWED_PATHS` in `.env` (comma-separated). Note: this **overrides** all defaults, so include `~/.claude` if you want plan mode to work:

```bash
ALLOWED_PATHS=/your/project,/other/path,~/.claude
```

### 3. Configure MCP

... (truncated)