Claude Telegram Agent

A generic, reusable bridge between Claude Code CLI and Telegram. Deploy on any server in a persistent tmux session — interact with Claude Code from your phone.

Features

• Text messages → Claude Code processes and responds
• Voice notes → Transcribed via Groq Whisper, then processed by Claude
• Audio files → Same transcription pipeline
• Multi-part messages → Automatically buffered and merged
• Auto-restart → Tmux loop restarts on crash
• Boot persistence → Crontab auto-start on server reboot
• Access control → Restrict by Telegram chat ID

Quick Install

# On your server (Ubuntu with Node.js 22+)
curl -sSL https://raw.githubusercontent.com/ljniox/claude-telegram-agent/main/scripts/install.sh | bash

Manual Install

git clone https://github.com/ljniox/claude-telegram-agent.git
cd claude-telegram-agent
npm install
cp .env.example .env
# Edit .env with your tokens
nano .env

Configuration

Edit .env:

Variable	Required	Description
TELEGRAM_BOT_TOKEN	Yes	From @BotFather on Telegram
ALLOWED_CHAT_IDS	Yes	Your Telegram user ID (comma-separated)
GROQ_API_KEY	No	For voice transcription (free: console.groq.com)
TRANSCRIBE_LANG	No	Language code (default: fr)
MAX_TURNS	No	Claude max tool turns (default: 25)
TIMEOUT_MS	No	Claude timeout in ms (default: 180000)
PROJECT_DIR	No	Working directory for Claude (default: repo root)

Customize Your Agent

Edit CLAUDE.md to define your agent's role and context:

# My Custom Agent

You are a [role] agent. You manage [what].

## Your tools
- Database: PostgreSQL at $DATABASE_URL
- API: https://api.example.com

## Your tasks
- Monitor X every morning
- Alert me when Y happens
- Keep Z up to date

Start

# Start in persistent tmux session
./scripts/start.sh

# Or run directly
node claude-bridge.js

Commands

Command	Description
/help	Show available commands
/status	Check agent status
Send any text	Claude processes it
Send voice note	Transcribed + processed

Architecture

Telegram App (your phone)
    ↕
Telegram Bot API
    ↕
claude-bridge.js (Node.js, tmux)
    ↕
claude -p "message" --dangerously-skip-permissions
    ↕
Claude Code CLI (reads CLAUDE.md, uses tools)
    ↕
Your server (files, databases, APIs)

Use Cases

• CRM Agent — Manage clients, send reminders, track pipeline
• DevOps Agent — Monitor servers, deploy, check logs
• Content Agent — Generate posts, schedule publications
• Research Agent — Search, summarize, analyze documents
• Personal Assistant — Notes, reminders, task management

License

MIT