ccpa-telegram

A Telegram bot that provides access to Claude Code as a personal assistant. Run Claude Code in any directory and interact with it through Telegram.

Features

• Chat with Claude Code via Telegram
• Send images and documents for analysis
• Voice message support with local Whisper transcription
• File sending - Claude can send files back to you
• Persistent conversation sessions per user
• Configurable Claude settings per project
• Multi-user support with access control

How It Works

This bot runs Claude Code as a subprocess in your chosen working directory. Claude Code reads all its standard configuration files from that directory, exactly as it would when running directly in a terminal:

• CLAUDE.md - Project-specific instructions and context
• .claude/settings.json - Permissions and tool settings
• .claude/commands/ - Custom slash commands
• .mcp.json - MCP server configurations

This means you get the full power of Claude Code - including file access, code execution, and any configured MCP tools - all accessible through Telegram.

For complete documentation on Claude Code configuration, see the Claude Code documentation.

Prerequisites

• Node.js 18+
• Claude Code CLI installed and authenticated.
• A Telegram bot token (from @BotFather). See Creating a Telegram Bot for instructions.
• ffmpeg (required for voice messages) - install with brew install ffmpeg on macOS

Quick Start

# Initialize a new project
npx ccpa-telegram init

# Edit ccpa.config.json with your bot token and allowed user IDs

# Start the bot
npx ccpa-telegram

Installation

Using npx (recommended)

npx ccpa-telegram init --cwd ./my-project
npx ccpa-telegram --cwd ./my-project

Configuration

ccpa.config.json

Create a ccpa.config.json file in your project directory:

{
  "telegram": {
    "botToken": "YOUR_BOT_TOKEN_HERE"
  },
  "access": {
    "allowedUserIds": [123456789]
  },
  "claude": {
    "command": "claude"
  },
  "logging": {
    "level": "info"
  },
  "transcription": {
    "model": "base.en",
    "showTranscription": true
  }
}

Configuration Options

| Option | Description | Default | | ------------------------------- | -------------------------------------------------------------- | ---------- | | telegram.botToken | Telegram bot token from BotFather | Required | | access.allowedUserIds | Array of Telegram user IDs allowed to use the bot | [] | | claude.command | Claude CLI command | "claude" | | logging.level | Log level: debug, info, warn, error | "info" | | transcription.model | Whisper model (see Voice Messages) | "base.en"| | transcription.showTranscription | Show transcribed text before Claude response | true |

Environment Variables

Environment variables override config file values:

| Variable | Description | | -------------------- | ------------------------------------ | | TELEGRAM_BOT_TOKEN | Telegram bot token | | ALLOWED_USER_IDS | Comma-separated user IDs | | CLAUDE_COMMAND | Claude CLI command | | LOG_LEVEL | Logging level | | WHISPER_MODEL | Whisper model for voice transcription | | SHOW_TRANSCRIPTION | Show transcription (true/false) |

Directory Structure

my-project/
├── ccpa.config.json      # Bot configuration
├── CLAUDE.md             # Claude system prompt
├── .claude/
│   └── settings.json     # Claude settings
└── .ccpa/
    └── users/
        └── {userId}/
            ├── uploads/      # Files FROM user (to Claude)
            ├── downloads/    # Files TO user (from Claude)
            └── session.json  # Session data

CLI Commands

# Show help
npx ccpa-telegram --help

# Initialize config file
npx ccpa-telegram init
npx ccpa-telegram init --cwd ./my-project

# Start the bot
npx ccpa-telegram
npx ccpa-telegram --cwd ./my-project

Bot Commands

| Command | Description | | -------- | -------------------------- | | /start | Welcome message | | /help | Show help information | | /clear | Clear conversation history |

Creating a Telegram Bot

To create a new Telegram bot and get your bot token:

1. Open Telegram and message @BotFather
2. Send /newbot command
3. Choose a display name for your bot (e.g., "My Claude Assistant")
4. Choose a username - must be unique and end with bot (e.g., my_claude_assistant_bot). The length of the username must be between 5 and 32 characters.
5. BotFather will reply with your bot token (looks like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
6. Copy this token to your ccpa.config.json

For detailed instructions, see the Telegram Bot API documentation.

Finding Your Telegram User ID

To find your Telegram user ID:

1. Message @userinfobot on Telegram
2. It will reply with your user ID
3. Add this ID to allowedUserIds in your config

Voice Messages

Voice messages are transcribed locally using Whisper via the nodejs-whisper package. No audio data is sent to external services.

Prerequisites for Voice Messages

Voice transcription requires additional setup:

1. ffmpeg - For audio conversion

   # macOS
   brew install ffmpeg
   
   # Ubuntu/Debian
   sudo apt install ffmpeg

2. CMake - For building the Whisper executable

   # macOS
   brew install cmake
   
   # Ubuntu/Debian
   sudo apt install cmake

3. Download and build Whisper - Run this once after installation:

   npx nodejs-whisper download

   This downloads the Whisper model and compiles the whisper-cli executable. The build process takes a few minutes.

Whisper Models

| Model | Size | Speed | Quality | | ---------------- | ------- | -------- | ------------------------------ | | tiny | ~75 MB | Fastest | Basic quality | | tiny.en | ~75 MB | Fastest | English-only, slightly better | | base | ~142 MB | Fast | Good for clear speech | | base.en | ~142 MB | Fast | English-only (default) | | small | ~466 MB | Medium | Good multilingual | | small.en | ~466 MB | Medium | English-only | | medium | ~1.5 GB | Slower | Very good multilingual | | medium.en | ~1.5 GB | Slower | English-only | | large-v1 | ~2.9 GB | Slowest | Best quality (v1) | | large | ~2.9 GB | Slowest | Best quality (v2) | | large-v3-turbo | ~1.5 GB | Fast | Near-large quality, faster |

First run: The selected model will be downloaded automatically. Subsequent runs use the cached model.

Supported Languages

Whisper supports 50+ languages including English, German, Spanish, French, and many more. Use models without .en suffix for multilingual support.

Sending Files to User

Claude can send files back to you through Telegram. Each user has a dedicated downloads/ folder, and Claude is informed of this path in every prompt.

How It Works

1. Claude writes a file to your downloads folder (e.g., .ccpa/users/{userId}/downloads/report.pdf)
2. The bot detects the new file after Claude's response completes
3. The file is sent to you via Telegram (as a document)
4. The file is deleted from the server after successful delivery

Example Usage

Ask Claude to create and send you a file:

Create a simple hello.txt file in my downloads folder with "Hello World" content

Claude will write the file to your downloads path, and the bot will automatically send it to you.

Supported Files

Any file type that Telegram supports can be sent, including:

• Documents (PDF, TXT, CSV, JSON, etc.)
• Images (PNG, JPG, etc.)
• Archives (ZIP, TAR, etc.)

Security Notice

Important: Conversations with this bot are not end-to-end encrypted. Messages pass through Telegram's servers and are processed by the Claude API. Do not share sensitive information such as:

• Passwords or API keys
• Personal identification numbers
• Financial information
• Confidential business data
• Any other private or sensitive data

This bot is intended for development assistance and general queries only. Treat all conversations as potentially visible to third parties.

License

ISC