If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/telegramdesktop/tdesktop shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit today
• 4 active contributors
• Other licensed
• CI configured
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 72% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live telegramdesktop/tdesktop repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/telegramdesktop/tdesktop.

What it runs against: a local clone of telegramdesktop/tdesktop — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in telegramdesktop/tdesktop | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch dev exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of telegramdesktop/tdesktop. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/telegramdesktop/tdesktop.git
#   cd tdesktop
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of telegramdesktop/tdesktop and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "telegramdesktop/tdesktop(\\.git)?\\b" \\
  && ok "origin remote is telegramdesktop/tdesktop" \\
  || miss "origin remote is not telegramdesktop/tdesktop (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify dev >/dev/null 2>&1 \\
  && ok "default branch dev exists" \\
  || miss "default branch dev no longer exists"

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "Telegram/CMakeLists.txt" \\
  && ok "Telegram/CMakeLists.txt" \\
  || miss "missing critical file: Telegram/CMakeLists.txt"
test -f ".github/workflows/linux.yml" \\
  && ok ".github/workflows/linux.yml" \\
  || miss "missing critical file: .github/workflows/linux.yml"
test -f ".github/workflows/win.yml" \\
  && ok ".github/workflows/win.yml" \\
  || miss "missing critical file: .github/workflows/win.yml"
test -f ".github/workflows/mac.yml" \\
  && ok ".github/workflows/mac.yml" \\
  || miss "missing critical file: .github/workflows/mac.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/telegramdesktop/tdesktop"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Telegram Desktop is the official cross-platform (Windows, macOS, Linux) desktop client for Telegram messaging, built in C++ with Qt 6/5.15, implementing the MTProto secure protocol for encrypted peer-to-peer and group communication. It provides a full-featured messaging UI with support for chats, calls, channels, and file sharing, compiled for 64-bit systems with native platform integrations. Single monorepo structured as: Telegram/ root contains CMakeLists.txt master build; platform-specific code branches by OS (Windows, macOS, Linux backends); .github/workflows/ orchestrates cross-platform CI; .agents/ and .claude/ contain AI-assisted development tooling; third-party dependencies vendored or patched in external submodules (.gitmodules references them).

End-users running Windows 7+, macOS 10.13+, or Linux who need a desktop Telegram client; open-source contributors interested in cross-platform C++/Qt desktop development, cryptography (MTProto/OpenSSL), and real-time messaging systems.

Highly mature production system: active development with 11+ GitHub Actions CI/CD workflows (linux.yml, mac.yml, win.yml, snap.yml, flatpak.yml), multi-platform releases via GitHub releases, automated changelog generation, and GPLv3 licensing. Commits to master branch are continuous; this is Telegram's official, battle-tested client.

Low technical risk as official Telegram product, but large monolithic codebase (24.8MB C++, 10K+ files) makes onboarding steep. Dependencies managed via third-party bundling (Qt 6, OpenSSL 3.2.1, WebRTC tg_owt, zlib, LZMA SDK) with patched Qt libraries—updates require coordination. No visible package.json; build requires CMake 3.16+ and platform-specific toolchains (MSVC/clang/gcc).

Active development includes automated workflows: copyright year updates (copyright_year_updater.yml), user-agent updates (user_agent_updater.yml), unused styles detection (unused_styles_updater.yml), and changelog generation (changelog.yml). CI status badges for Windows/macOS/Linux indicate continuous build validation. Recent focus appears to be on multi-platform stability and automated maintenance.

git clone --recursive https://github.com/telegramdesktop/tdesktop.git
cd tdesktop
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

(Exact build steps vary by OS; see Telegram/CMakeLists.txt and .github/workflows/* for platform-specific configuration)

Daily commands: Platform-dependent; use CMake: cmake -B build && cmake --build build. For development, see .github/workflows/linux.yml, mac.yml, win.yml for exact compiler flags and dependency installation (e.g., apt-get install qt6-base-dev on Linux, Xcode CLT on macOS, MSVC on Windows).

• CMakeLists.txt — Root build configuration that orchestrates the entire C++ desktop application compilation; essential for understanding dependencies and platform-specific build targets.
• Telegram/CMakeLists.txt — Main Telegram application build rules; defines how the messenger executable is assembled from source modules.
• .github/workflows/linux.yml — CI/CD pipeline for Linux builds; shows automated testing and release processes that catch regressions.
• .github/workflows/win.yml — CI/CD pipeline for Windows builds; demonstrates platform-specific compilation and packaging conventions.
• .github/workflows/mac.yml — CI/CD pipeline for macOS builds; reveals signing, notarization, and distribution requirements for Apple platforms.
• README.md — Documents project scope, supported systems, build instructions, and licensing (GPLv3 with OpenSSL exception); foundation for onboarding.
• .github/CONTRIBUTING.md — Contribution guidelines and code standards; mandatory reading for any pull request author.

• MTProto Client (C++, OpenSSL, MTProto TL language) — Encrypts messages, maintains TLS session with Telegram servers, serializes/deserializes TL schema objects, handles re-connection logic.
  • Failure mode: Network errors cause message delivery delay; corrupted crypto state can lead to authentication failure and forced re-login.
• Qt UI Framework (Qt5/6, platform-specific backends (Cocoa on macOS, Win32 on Windows, X11/Wayland on Linux)) — Renders widgets, processes keyboard/mouse events, manages window lifecycle, coordinates with native OS window managers.
  • Failure mode: Memory leaks in event handlers can degrade responsiveness over time; crashes in native integrations require platform-specific debugging.
• Local Data Cache (SQLite, memory-mapped I/O) — Stores chat history, media metadata, and user profiles in SQLite; synchronizes with server state upon startup and connection recovery.
  • Failure mode: Corruption during power loss can lose recent messages; cache invalidation bugs cause stale data

Add a New Animation Asset

1. Create or export TGS animation file (Telegram animated sticker format) (Telegram/Resources/animations/{category}/{name}.tgs)
2. Register the animation in the appropriate CMakeLists.txt resource section (Telegram/CMakeLists.txt)
3. Reference the asset in UI code via the resource system (Telegram/Resources/animations (consult existing .tgs usages in codebase))

Integrate a Platform-Specific Fix

1. Add CMake platform-specific conditional in root build config (CMakeLists.txt)
2. Implement platform-specific code path in source (typically guarded by preprocessor macros like DESKTOP_APP_WIN or DESKTOP_APP_MAC) (Telegram/CMakeLists.txt (reference implementation files))
3. Add or update the relevant platform CI workflow to test the fix (.github/workflows/{linux,win,mac}.yml)
4. Document the change in a contributing guide or inline comment (.github/CONTRIBUTING.md)

Update Build Dependencies

1. Add or modify dependency declaration in root CMakeLists.txt (e.g., find_package calls) (CMakeLists.txt)
2. Link the dependency in application CMakeLists.txt via target_link_libraries (Telegram/CMakeLists.txt)
3. Update CI workflows to install or cache new dependencies (.github/workflows/linux.yml or .github/workflows/win.yml (as applicable))
4. Update README build instructions if the dependency is external (README.md)

• C++ with Qt framework — Native desktop performance, cross-platform GUI abstraction, and low-level control over rendering and system integration on Windows, macOS, and Linux.
• CMake build system — Multi-platform compilation without platform-specific project files; supports conditional logic for Windows/macOS/Linux targets and dependency resolution.
• MTProto protocol (Telegram's custom protocol) — Secure end-to-end encrypted messaging with server authentication; designed specifically for Telegram's infrastructure.
• GitHub Actions CI/CD — Automated cross-platform builds, testing, and release packaging for all three major desktop platforms in a single workflow.
• TGS (Telegram Graphics) animations — Lightweight vector animations for UI feedback (dice rolls, loading states, emojis) that scale well on all screen densities.

• Monolithic C++ codebase instead of modular services

  • Why: Desktop applications require tight coupling between UI, crypto, and network I/O for low-latency local interactions.
  • Consequence: Easier to achieve responsive UI and offline support, but larger codebase complexity and longer compilation times.

• Local caching and offline-first message composition

  • Why: Users expect drafts to persist locally even without connectivity; improves perceived responsiveness.
  • Consequence: Requires careful synchronization logic to merge local state with server state upon reconnection; risk of duplicate sends if not handled correctly.

• Three separate CI workflows (Linux, macOS, Windows) instead of unified cross-compilation

  • Why: Each platform requires native toolchains, signing certificates (macOS), and deployment artifacts; no universal build container.
  • Consequence: Parallel build times are longer; but native builds catch platform-specific bugs early.

• GPLv3 with OpenSSL exception instead of permissive license

  • Why: Aligns with Telegram's free/open-source philosophy and protects derivative works.
  • Consequence: Restricts proprietary forks; contributors must accept GPL terms.

• This is not a CLI tool — it is exclusively a graphical desktop application (no headless/server mode).
• Does not provide a custom messaging protocol library for other projects — the MTProto implementation is tightly integrated into the UI.
• Does not support Android or iOS; this repository is desktop-only.
• Does not manage account creation or two-factor authentication flows at the application level — delegated to Telegram's online services.
• Not a mobile-first design; optimized for desktop screens with keyboard/mouse input.

No package.json: uses CMake exclusively—npm/yarn will fail. Recursive clone required: .gitmodules points to external repos; omit --recursive and third-party libs won't exist. Platform toolchain mandatory: Windows needs MSVC 2019+, macOS needs Xcode 12+, Linux needs gcc 10+ or clang 11+; using wrong compiler causes silent link failures. Qt patches: bundled Qt is patched; using system Qt6/Qt5 will likely break. Submodule locks: git submodule state must be in sync; git status and .gitmodules can diverge after branch switches. No Docker/dev container: .devcontainer.json exists but is minimal; most developers build natively on target OS.

• MTProto (Mobile Transport Protocol) — Core encryption and serialization protocol for all Telegram client-server communication; understanding MTProto message framing, key derivation, and authentication is essential to modifying network code in Telegram/SourceFiles/mtproto/.
• Qt Signal/Slot Event System — tdesktop's entire UI and async architecture depends on Qt's meta-object compiler (moc) and signal/slot connections for decoupled event handling; misusing this pattern breaks the async model.
• Cross-Platform Abstraction Layer (Platform-Specific Code Isolation) — Code under Telegram/SourceFiles/platform/ isolates OS-specific APIs (Win32, Cocoa, X11) behind common interfaces; understanding this pattern is critical to avoid platform-specific bugs when modifying window management, notifications, or file system access.
• CMake Modular Build Configuration — tdesktop uses CMake functions to conditionally compile code by platform and feature flags; mastering target definition, generator expressions, and source grouping is necessary to add features without breaking builds on unsupported platforms.
• OpenSSL 3.2.1 Cryptography (EVP API, TLS Handshake) — MTProto key negotiation and message encryption use OpenSSL; understanding EVP (high-level) vs. legacy low-level APIs, cipher modes, and hash algorithms is required for security-critical modifications.
• Objective-C++ Interoperability (C++/Cocoa Bridge) — macOS-specific files in Telegram/SourceFiles/platform/mac/ use Objective-C++ to call Cocoa APIs (NSWindow, NSApplication) from C++; syntax (@interface, memory management rules) differs from pure C++ and pure Objective-C.
• Recursive Git Submodules and Dependency Pinning — tdesktop pins exact versions of Qt, WebRTC (tg_owt), and third-party libs via .gitmodules and submodule commit hashes; shallow clones or wrong submodule state silently cause link/runtime failures that are hard to debug.

• desktop-app/tg_owt — WebRTC implementation vendored as submodule in tdesktop; handles voice/video call infrastructure and media streams.
• telegramdesktop/lib_ui — Companion repository containing reusable Qt UI components and widgets used by tdesktop; likely extracted to support modularity.
• telegramdesktop/lib_base — Core utilities library (logging, threading, async primitives) likely used across Telegram projects; defines foundational abstractions.
• signalapp/Signal-Desktop — Alternative cross-platform desktop messaging client using Electron/TypeScript; architectural comparison for event-driven messaging UI design.
• riverbankcomputing/PyQt6 — Python bindings for Qt 6; useful reference for understanding Qt signal/slot mechanism and event loop architecture used in tdesktop's C++ codebase.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add automated UI screenshot regression tests for animation assets

The repo contains hundreds of TGS (Telegram Sticker) animation files in Telegram/Resources/animations/ with no apparent test coverage. A new contributor could create a GitHub Action that renders sample animations and compares them against baseline screenshots to catch regressions when animation assets are modified. This would catch visual bugs early and protect critical UX assets.

• [ ] Create .github/workflows/animation-regression-tests.yml
• [ ] Write a test script in .github/scripts/ that loads TGS files from Telegram/Resources/animations/ and generates PNG previews
• [ ] Set up baseline screenshot storage (e.g., in .github/baselines/)
• [ ] Configure the workflow to run on PRs that modify files matching Telegram/Resources/animations/**
• [ ] Document the process in .github/CONTRIBUTING.md

Create comprehensive platform-specific build documentation with troubleshooting

While the repo has working CI/CD workflows for Windows, macOS, and Linux (.github/workflows/win.yml, mac.yml, linux.yml), there is no detailed contributor guide for local development builds per platform. New contributors struggle to set up builds locally. A maintainer-quality guide would reduce friction and support requests.

• [ ] Create BUILDING.md at repo root documenting Windows (MSVC/Qt setup), macOS (Xcode/homebrew), and Linux (apt/gcc) build procedures
• [ ] Cross-reference specific build dependencies from CMakeLists.txt and .devcontainer.json
• [ ] Add troubleshooting section linking to common issues and their solutions from existing GitHub issues
• [ ] Include platform-specific environment setup (Qt paths, SDK versions) derived from .github/workflows/ configs
• [ ] Add quick-start section pointing to .devcontainer.json for containerized builds

Implement CI workflow for code style and unused styles detection consistency

The repo already has .github/workflows/unused_styles_updater.yml suggesting style management is important, but there is no pre-commit linting workflow to catch style violations before merge. Adding a linting/style-check workflow would maintain code quality and prevent inconsistencies from being introduced.

• [ ] Create .github/workflows/style-lint.yml that runs on PRs
• [ ] Determine the project's C++ style guide (likely matching existing code patterns) and integrate clang-format or similar tool
• [ ] Integrate the unused_styles checker from unused_styles_updater.yml into the new workflow as a blocking check
• [ ] Add a .clang-format file at repo root if missing, or reference existing style configuration
• [ ] Document style requirements in .github/CONTRIBUTING.md with instructions for local style checking

• Add missing unit tests for Telegram/SourceFiles/mtproto/ protocol parsing: there are encryption/serialization functions without corresponding test files in what appears to be a test-light area of the codebase.
• Document the CMake build system: create a BUILD.md with platform-specific setup (Xcode, MSVC, gcc versions, Qt path configuration) by extracting and expanding the implicit knowledge in .github/workflows/*.yml.
• Implement automated style checking: the unused_styles_updater.yml workflow exists but there's no pre-commit hook or lint target; add a CMake test target that runs style validation on changed files.

The Telegram Desktop codebase shows reasonable security practices with automated CI/CD workflows for multiple platforms and dependency monitoring via Dependabot. However, the analysis is limited by: (1) empty dependency information preventing vulnerability assessment, (2) development tool scripts committed to the repository, (3) lack of visible security policy. No critical vulnerabilities are apparent from the file structure alone. The project would benefit from explicit security documentation and verification that development tools are not inadvertently including sensitive data in builds. The presence of comprehensive GitHub workflows and the maintenance of a major security-sensitive application suggests active security practices not fully visible in this structural analysis.

• Medium · Clipboard Access Scripts in Repository — .claude/grab_clipboard.ps1, .claude/grab_clipboard.sh. The repository contains clipboard access scripts (.claude/grab_clipboard.ps1 and .claude/grab_clipboard.sh) that could potentially be misused to extract sensitive information. These scripts should not be part of the distributed codebase if they access user data. Fix: Remove clipboard access utilities from the repository or ensure they are development-only tools that are properly documented and not included in production builds. Add to .gitignore if they should not be tracked.
• Low · Development Configuration Files in Repository — .agents/, .claude/, .devcontainer.json, AGENTS.md, CLAUDE.md. Multiple development and AI assistant configuration files are committed to the repository (.agents, .claude, .devcontainer.json). While not directly a vulnerability, these could expose development practices and tooling preferences. Fix: Consider moving development-specific configurations to separate documentation or ensure sensitive configuration is added to .gitignore. Review contents for any hardcoded paths or credentials.
• Low · Incomplete Dependency Analysis — Dependencies/Package file, CMakeLists.txt. The provided dependency file content is empty, making it impossible to perform comprehensive dependency vulnerability scanning. The project uses CMakeLists.txt for build configuration but transitive dependencies and their versions cannot be verified. Fix: Implement Software Composition Analysis (SCA) tools like Dependabot (already configured), OWASP Dependency-Check, or Snyk to continuously monitor dependencies. Maintain a complete lock file (conan.lock, vcpkg.json.lock, etc.) in version control.
• Low · Lack of Visible Security Policy Documentation — .github/ directory. While CONTRIBUTING.md exists, there is no visible SECURITY.md file defining vulnerability disclosure procedures, which is a best practice for security-conscious projects. Fix: Create a SECURITY.md file following the GitHub template at https://github.com/security/vulnerability-reporting to establish a responsible disclosure policy.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.