An open-source desktop tool for converting and analyzing exported Telegram chats.

Read this in other languages: Русский

---

📸 Preview

---

🧭 Quick links

• Install & run from source: docs/INSTALL.md
• CLI Documentation: docs/CLI.md
• Learn the app (Help): EN Introduction • EN All topics • RU Docs
• Contribute: CONTRIBUTING.md
• More: Development History • Project Vision

---

🧩 Overview

Tkonverter is a free and open-source desktop application designed to convert large Telegram JSON exports into a clean .txt format.

The project was initially created to preprocess chat data for use with Large Language Models (LLMs) like Gemini. Its features are centered around the need to manage LLM context windows effectively—either by compressing information (e.g., shortening quotes, truncating names) to save tokens, or by enriching it (e.g., including reactions, polls, Markdown) for higher-quality analysis.

While its primary goal is LLM pre-processing, it is a versatile tool that may be useful for any chat archiving or analysis needs.

---

🚀 Key Features

🔄 Advanced Conversion & Context Control

• Flexible Profiles: Supports group chats, personal conversations, channels, and posts. The app automatically detects the correct profile in most cases.
• Context Saving Tools: Reduce token count with options to automatically shorten replied-to message snippets and truncate long usernames.
• Rich Context Options: Choose to include detailed information like reactions, poll results, links, and full Markdown formatting for the highest quality input.
• Fine-Grained Control: Toggle the visibility of timestamps, service messages, and technical information.
• Anonymization Module: Before sharing chats with an LLM or third party, anonymize names and links. Replace display names with masks (e.g. [ИМЯ 1] or User 1), hide or mask URLs (simple placeholder, domain-only, or indexed), use presets and custom domain/regex filters. Configurable via the GUI or JSON config for CLI.

📊 Analytics for LLM Pre-processing

• Token & Character Counting: Calculate the exact token count (using Hugging Face tokenizers) or character count to understand how formatting choices impact the final data size.
• Interactive Chart: Visualize message volume over time with a sunburst chart inspired by KDE Filelight.
• Data Filtering: Exclude irrelevant time periods from your export by clicking on chart segments, allowing you to refine the context sent to a model.

🤖 Optional AI Integration

• Hugging Face Support: For precise, model-specific token analysis.
• Built-in Installer: Install required Python libraries (transformers, huggingface_hub) and download models directly from the UI—no terminal needed.

🧑‍💻 User Experience & Tooling

• Cross-Platform: Built with Python and PyQt6.
• Theming: Supports light and dark modes, with auto-detection of your system's theme.
• Powerful Launcher: A launcher.sh script simplifies dependency management in a virtual environment, running, and debugging.
• CLI Interface: Full-featured command-line interface for automation and script integration.

---

🛠 Installation

Currently, the primary installation method is by running from the source code.

🐍 From Source (Linux/macOS)

The launcher.sh script will automatically create a virtual environment and install dependencies from requirements-gui.txt.

git clone https://github.com/Loganavter/Tkonverter.git
cd Tkonverter
chmod +x launcher.sh
./launcher.sh run

Use ./launcher.sh --help for a full list of commands (including recreate, delete, profile). Dependencies: requirements-gui.txt for GUI (and CLI from repo); requirements-cli.txt for CLI-only (e.g. server, no PyQt). See docs/INSTALL.md.

🪟 Windows

See docs/INSTALL.md or install it from last release with inno setup.

---

🧪 Usage

Graphical Interface

1. Launch the application: ./launcher.sh run.
2. Drag and drop your result.json file (from a Telegram export) into the application window.
3. Configure the formatting options on the left panel.
4. (Optional) Open Anonymization to hide or mask names and links before export.
5. (Optional) Click "Recalculate" to analyze tokens and open the chart for visualization.
6. Click "Save to file..." to export the result as a .txt file.

Command Line Interface (CLI)

# Simple conversion
./tkonverter-cli.sh convert -i result.json -o output.txt

# Convert with custom settings
./tkonverter-cli.sh convert -i result.json -o output.txt --profile personal --no-time

# Analyze statistics
./tkonverter-cli.sh analyze -i result.json --chars-only

# Show file information
./tkonverter-cli.sh info -i result.json --detailed

# Get help
./tkonverter-cli.sh --help
./tkonverter-cli.sh convert --help

---

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for development setup, coding guidelines, and packaging notes. Report issues and propose PRs via GitHub.

---

📄 License

This project is licensed under the MIT License. See LICENSE.txt for details.

---

⭐ Star History