Telegram Deep Research Agent

Intelligent Telegram channel search agent powered by Claude Agent SDK with Query Fan-Out technology.

Features

• Query Fan-Out — natural language queries are expanded into keywords for better search coverage
• Parallel search across multiple Telegram channels with deduplication
• Conversational context — follow-up questions remember previous context
• Source links in responses (t.me/channel/message_id)
• 6-month time filter — only recent messages are included
• No local database — stateless, live search only

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  User: "Какие новости были про claude code?"                    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  1. Query Expander (Claude Haiku)                               │
│     Extracts keywords from natural language                     │
│                                                                 │
│     "Какие новости про claude code?"                            │
│         → ["claude code", "anthropic", "Claude Code"]           │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  2. Multi-Search (Telethon User API)                            │
│     Parallel search for each keyword across all channels        │
│                                                                 │
│     search("claude code")  → 27 msgs                            │
│     search("anthropic")    → 15 msgs                            │
│     search("Claude Code")  → 27 msgs (duplicates)               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  3. Deduplication                                               │
│     Remove duplicates by (channel_username, message_id)         │
│                                                                 │
│     69 raw messages → 33 unique messages                        │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  4. Synthesis (Claude Haiku)                                    │
│     Analyze messages and generate structured response           │
│     with themes, trends, and source links                       │
└─────────────────────────────────────────────────────────────────┘

Setup

1. Install dependencies

# Install uv if not installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install project dependencies
uv sync

2. Configure environment

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

Required credentials:

• TG_BOT_TOKEN — Get from @BotFather
• TG_API_ID / TG_API_HASH — Get from my.telegram.org/apps
• TG_PHONE — Your phone number for Telethon auth
• ANTHROPIC_API_KEY — Your Anthropic API key
• ANTHROPIC_BASE_URL — (Optional) Custom API endpoint

3. Configure channels

Edit config/channels.yaml:

channels:
  - name: "AI News"
    username: "@ai_news_channel"
    enabled: true
  - name: "Tech Updates"
    username: "@tech_channel"
    enabled: true

4. Run

uv run python -m src.main

On first run, Telethon will ask for auth code via terminal.

Usage

In Telegram, message your bot:

• Send any question to search channels (natural language supported)
• /channels — List configured channels
• /new — Clear conversation context
• /help — Show help

Example

User: Какие новости были про claude code?

Bot:
💬 Запрос: Какие новости были про claude code?
🧠 Анализирую запрос...
🔑 Ключевые слова: claude code, anthropic, Claude Code
🔍 Ищу по каналам...
📊 Найдено 33 сообщений в 3 каналах
🤖 Генерирую ответ...
✅ Готово

[Structured response with themes and source links]

Project Structure

tg-deep-research/
├── config/
│   ├── channels.yaml        # Channel list
│   └── settings.yaml        # App settings (prompts, limits)
├── src/
│   ├── agent/
│   │   ├── claude_client.py   # Claude SDK integration
│   │   ├── query_expander.py  # Query Fan-Out (NL → keywords)
│   │   └── session_manager.py # Conversation context
│   ├── bot/
│   │   └── handlers.py        # Telegram bot handlers
│   ├── search/
│   │   ├── telethon_client.py # Telethon search wrapper
│   │   └── parallel_search.py # Multi-channel search + dedup
│   ├── utils/
│   │   └── config.py          # Configuration loader
│   └── main.py                # Entry point
└── pyproject.toml

Configuration

settings.yaml

search:
  max_messages_per_channel: 10  # Max messages per channel per keyword
  parallel_limit: 5             # Concurrent channel searches
  flood_sleep_threshold: 60     # Telethon flood wait threshold
  months_back: 6                # Only messages from last N months

claude:
  system_prompt: |
    Your custom system prompt for response generation...
  session_timeout_minutes: 30   # Conversation context TTL

Tech Stack

• Claude Agent SDK — LLM integration (query expansion + synthesis)
• Telethon — Telegram User API for channel search
• aiogram 3.x — Telegram Bot API
• Pydantic — Configuration management