telegram-download-chat: Instructions file for Codex

CLAUDE.md

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

Project Overview

Telegram Download Chat is a Python CLI utility that downloads and analyzes Telegram chat history. It provides both command-line and GUI interfaces for downloading messages from chats, groups, channels, or archived exports and saving them in JSON/TXT formats.

Key Components

• Core Engine (core/ package): Contains TelegramChatDownloader plus helper modules (auth, config, download, entities, media, messages, context, render, progress, comments, citations, reactions, update_checker) built on Telethon
• CLI Interface (cli.py): Command-line interface with argument parsing and async message processing
• GUI Interface (gui_app.py): PySide6-based graphical interface with threading for async operations
• MCP Server (mcp/ package): Model Context Protocol server exposing Telegram chat tools for AI assistants
• Configuration (paths.py): Handles config file management and application directories

Architecture

The application follows a modular design:

1. Configuration Layer: YAML-based config with API credentials and user settings
2. Telegram Client Layer: Telethon wrapper for authenticated API communication
3. Processing Layer: Message filtering, date splitting, format conversion
4. Interface Layer: CLI and GUI frontends sharing the same core functionality

Development Commands

Use .venv virtual environment.

Setup Development Environment

# Install in development mode with all dependencies
pip install -e ".[dev,gui]"

# Or install from requirements
pip install -r requirements.txt

Testing

# Run tests
pytest

# Run tests with async support
pytest -v

# Run specific test
pytest tests/test_telegram_download_chat.py::TestClass::test_method

# Opt-in end-to-end export tests against a live Telegram group (skipped by default).
# Requires an authenticated session and membership in the test group.
TG_E2E=1 pytest -m e2e   # override the group via TG_E2E_GROUP