CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

Telegram Channel Analyzer Bot — fetches public channel history via Telethon, analyzes with Claude AI (chunked summarization pipeline), delivers reports via aiogram bot.

Stack

Python 3.12, async throughout
aiogram 3 — Telegram bot interface (commands, inline keyboards, progress messages)
Telethon — userbot client for reading public channel history
anthropic (AsyncAnthropic) — Claude API with streaming
pydantic-settings — config from environment variables

Architecture

Both aiogram and Telethon share one asyncio loop (no threads)
Telethon client is attached to the bot instance in __main__.py
Analysis pipeline: Fetch → Chunk (token-bounded) → Summarize each chunk → Synthesize final report
Rate limit handling: semaphore(1), 60s cooldown between chunks, retry with backoff on 429
Output: Markdown→HTML conversion, split on section boundaries at 4000 chars

Key Files

bot/config.py — all settings from env vars, CLAUDE_MODEL selects the model
bot/services/analyzer.py — Claude API calls, adaptive thinking only for opus-4-6
bot/services/chunker.py — MAX_TOKENS_PER_CHUNK and CHARS_PER_TOKEN control chunking
bot/prompts/ — prompt templates per report type (chunk_summary.py, synthesis.py)

Running

Container-based: Containerfile + compose.yml
--login flag for interactive Telethon session creation
Session persists in data/ volume
.env file must not have inline comments (Podman/Docker limitation)

Common Tasks

To change chunk size: edit MAX_TOKENS_PER_CHUNK in bot/services/chunker.py
To add a report type: add to ReportType enum, add prompts in both prompts/ files
To change model: set CLAUDE_MODEL env var; thinking params auto-adapt in analyzer.py

1.9 KiB Raw Blame History