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/TGX-Android/Telegram-X 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 — Single-maintainer risk — review before adopting

• Last commit 5d ago
• 2 active contributors
• GPL-3.0 licensed
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 81% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows detected
• ⚠ 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 TGX-Android/Telegram-X repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/TGX-Android/Telegram-X.

What it runs against: a local clone of TGX-Android/Telegram-X — 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 TGX-Android/Telegram-X | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 35 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of TGX-Android/Telegram-X. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/TGX-Android/Telegram-X.git
#   cd Telegram-X
#
# 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 TGX-Android/Telegram-X and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "app/build.gradle.kts" \\
  && ok "app/build.gradle.kts" \\
  || miss "missing critical file: app/build.gradle.kts"
test -f "app/jni/CMakeLists.txt" \\
  && ok "app/jni/CMakeLists.txt" \\
  || miss "missing critical file: app/jni/CMakeLists.txt"
test -f "app/jni/bridge.cpp" \\
  && ok "app/jni/bridge.cpp" \\
  || miss "missing critical file: app/jni/bridge.cpp"
test -f "app/proguard-rules.pro" \\
  && ok "app/proguard-rules.pro" \\
  || miss "missing critical file: app/proguard-rules.pro"
test -f "app/src/google/java/org/thunderdog/challegram/push/FirebaseDeviceTokenRetriever.kt" \\
  && ok "app/src/google/java/org/thunderdog/challegram/push/FirebaseDeviceTokenRetriever.kt" \\
  || miss "missing critical file: app/src/google/java/org/thunderdog/challegram/push/FirebaseDeviceTokenRetriever.kt"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 35 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~5d)"
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/TGX-Android/Telegram-X"
  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 X is an official alternative Android client for Telegram messenger built on TDLib (Telegram Database Library), offering a slick, modern UI written primarily in Java/Kotlin. It implements the complete Telegram API and MTProto secure protocol, providing a fully functional Telegram client with custom rendering, VoIP support (via WebRTC/tgcalls), and native media codecs (Opus, WebP, YUV, FLAC via CMake-built dependencies). Monorepo structured as app/ root with jni/ subdirectory containing native C/C++ bridges. The CMakeLists.txt orchestrates 10+ BuildX.cmake files for media libraries (BuildOpus.cmake, BuildWebp.cmake, BuildFlac.cmake, etc.), tgvoip/ contains voice codec stack (tgcalls, WebRTC, SRTP, RNNoise), and third_party/ vendors androidx-media JNI headers. Java/Kotlin code implicitly resides in src/ (not shown in file list but standard Android structure).

Android developers and Telegram power users who want to understand how a production Telegram client is built; contributors to the TGX-Android organization maintaining the official alternative client; security researchers examining MTProto implementation details in Android; mobile engineers learning modern Android architecture with TDLib integration.

Production-ready and actively maintained: deployed on Google Play and Huawei AppGallery with public release channels (@tgx_log). The codebase shows 17.6MB of Java and significant native C++/CMake build infrastructure for media codecs. Commits appear recent based on build tooling updates, though exact commit history isn't visible in the provided metadata.

High complexity from deeply integrated native dependencies (WebRTC, Opus, libogg, libvorbis, libjpeg, libpng, libyuv, RNNoise) requiring 5.34GB disk space and custom CMake builds—version mismatches or build environment differences can break compilation. Single organizational maintainer (TGX-Android) means no distributed governance. Sensitive code paths around MTProto encryption and VoIP require careful security auditing.

Active native codec pipeline development visible in jni/ build system; VoIP stack being maintained in app/jni/tgvoip/ with tgcalls integration (BuildTgCalls.cmake). Recent work on platform-specific builds (Huawei AppGallery support via agconnect-services.json). Build infrastructure actively refined via gradle.kts.

git clone --recursive --depth=1 --shallow-submodules https://github.com/TGX-Android/Telegram-X tgx
cd tgx
scripts/./setup.sh
# Create keystore.properties with signing credentials (see README step 3)
# Then open in Android Studio or gradle build

Daily commands:

# After setup.sh and keystore.properties created:
cd tgx
./gradlew assembleDebug          # Build debug APK
./gradlew installDebug            # Install to connected device
# Or open in Android Studio and use built-in emulator/device runners

• app/build.gradle.kts — Primary build configuration defining dependencies, SDK versions, and compilation settings for the entire Telegram X application
• app/jni/CMakeLists.txt — Root CMake configuration orchestrating native library builds (WebRTC, Opus, Rlottie, FLAC) essential for media handling and VoIP
• app/jni/bridge.cpp — JNI bridge layer connecting Java/Kotlin code to native C++ implementations for performance-critical operations
• app/proguard-rules.pro — Code obfuscation and optimization rules ensuring app size and security after minification
• app/src/google/java/org/thunderdog/challegram/push/FirebaseDeviceTokenRetriever.kt — Firebase integration for push notifications, critical for real-time message delivery
• app/jni/tgvoip/CMakeLists.txt — VoIP-specific native build configuration for TGCalls, WebRTC, and SRTP dependencies required for secure voice calls

Add a new location-based feature

1. Create new location retriever interface in app/src/google/java/org/thunderdog/challegram/location/ (app/src/google/java/org/thunderdog/challegram/location/YourLocationRetriever.java)
2. Register implementation in LocationRetrieverFactory.java factory method (app/src/google/java/org/thunderdog/challegram/location/LocationRetrieverFactory.java)
3. Create corresponding UI controller extending MapControllerFactory pattern (app/src/google/java/org/thunderdog/challegram/ui/MapYourController.java)
4. Update build.gradle.kts with any new location API dependencies if needed (app/build.gradle.kts)

Add native media codec support

1. Create new Build*.cmake file following existing pattern (BuildOpus.cmake, BuildWebp.cmake) (app/jni/BuildYourCodec.cmake)
2. Add include() directive in root CMakeLists.txt to load your codec build (app/jni/CMakeLists.txt)
3. Create JNI wrapper in bridge.cpp to expose codec functionality to Java layer (app/jni/bridge.cpp)
4. Update proguard-rules.pro to preserve JNI native method declarations (app/proguard-rules.pro)

Integrate new push notification provider

1. Create new push notification retriever class extending DeviceTokenRetriever pattern (app/src/google/java/org/thunderdog/challegram/push/YourDeviceTokenRetriever.kt)
2. Create corresponding listener service for incoming push messages (app/src/google/java/org/thunderdog/challegram/service/YourListenerService.java)
3. Register new service in AndroidManifest.xml (not in file list, but standard location) (app/src/main/AndroidManifest.xml)
4. Add provider-specific dependencies and service configuration to build.gradle.kts (app/build.gradle.kts)

Enhance emoji or GIF support with new features

1. Update native emoji suggestions engine source file (app/jni/third_party/emoji_suggestions/emoji_suggestions.cpp)
2. Regenerate emoji data with new suggestions using data generator (app/jni/third_party/emoji_suggestions/emoji_suggestions_data.cpp)
3. Rebuild emoji/GIF processing in JNI bridge (app/jni/bridge.cpp)
4. Verify CMake includes BuildRlottie for animated sticker rendering (app/jni/CMakeLists.txt)

• TDLib (Telegram Data Library) — Official Telegram API abstraction layer providing secure MTProto communication and high-level Telegram protocol handling, eliminates need to reimplement protocol logic
• TGCalls + WebRTC — Standardized real-time communication stack for secure peer-to-peer voice/video calls with SRTP encryption and network resilience
• Opus Audio Codec — Modern, efficient, low-latency audio codec optimized for voice transmission and VoIP applications
• Firebase Cloud Messaging (FCM) — Reliable push notification delivery across Android devices via Google Play Services ecosystem
• CMake + NDK — Cross-platform native build system enabling C/C++ compilation for performance-critical media encoding/decoding and cryptography
• R8/ProGuard — Production code optimization and obfuscation reducing APK size and protecting intellectual property in release builds

• Heavy use of native C/C++ for media and crypto

  • Why: Provides 10-100x performance improvement for real-time audio/video processing and cryptographic operations
  • Consequence: Increased complexity, platform-specific compilation, harder to debug, requires NDK expertise from contributors

• Dependency on Firebase/Google Play Services

  • Why: Simplifies push notification infrastructure and provides battle-tested reliability at scale
  • Consequence: App requires Google Play Services on device; alternative Huawei AppGallery build needed for devices without Google Play

Disk space: setup requires 5.34GB free (487MB source + 4.85GB build artifacts)—shallow clone still needs large intermediate objects. Keystore outside tree: keystore.properties MUST be created in parent directory, not tracked by git (security measure, but easy to forget). LFS requirement: git-lfs must be installed and initialized (git lfs install) or large binary files won't download properly. CMake versions: Native build uses C++14/17 features and specific WebRTC/tgcalls API versions—mixing incompatible toolchain versions breaks silently. Platform limitation: Windows officially unsupported except via MSYS2—Linux/macOS strongly recommended. Firebase/Huawei dual-mode: If changing package name (app.id), must regenerate google-services.json AND agconnect-services.json or build fails cryptically.

• MTProto (Mobile Transport Protocol) — Telegram's custom encrypted protocol that Telegram X implements via TDLib—understanding MTProto is essential for grasping security model and wire format
• TDLib (Telegram Database Library) — The C++ abstraction layer that Telegram X depends on via JNI—decouples app from raw MTProto, manages state, handles offline sync, and encryption
• JNI (Java Native Interface) Bridging — Telegram X uses JNI bridge.cpp to call TDLib C++ from Kotlin/Java—critical for understanding performance-critical paths and memory management across language boundaries
• WebRTC (Real-Time Communication) — Telegram X integrates WebRTC via tgcalls and custom codecs (Opus, RNNoise) for peer-to-peer VoIP—understanding codec negotiation and NAT traversal explains call reliability
• Opus Audio Codec — Telegram X uses Opus (built via BuildOpus.cmake) as the primary audio codec for calls—low-latency, adaptive bitrate codec critical for VoIP quality
• CMake Modular Dependency Graph — app/jni/CMakeLists.txt uses separate BuildX.cmake files (BuildFlac, BuildWebp, etc.) to isolate library versions—understanding this pattern is key to modifying codec chains without breaking downstream builds
• Shallow Clone with Submodule Recursion — Build instruction uses --shallow-submodules --depth=1 to minimize disk footprint (4.85GB) while preserving nested dependencies (tdlib, tgcalls, WebRTC)—critical for CI/CD and large dev teams

• TGX-Android/tdlib — The core Telegram Database Library that Telegram X wraps—essential dependency providing MTProto implementation and message storage
• telegramdesktop/tdesktop — Official Telegram Desktop client sharing TDLib backend; reference implementation for protocol features that Telegram X mirrors
• TGX-Android/buildTools — Companion build infrastructure repo (implied by setup.sh execution)—likely contains pre-built CMake toolchains and dependency caches
• TGX-Android/tgcalls — Extracted VoIP call handling library that Telegram X integrates; separate repo enabling code reuse and WebRTC version isolation

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 CMake build validation and dependency version pinning for JNI modules

The repo has 8 separate CMakeLists.txt build files across app/jni and app/jni/tgvoip that build complex dependencies (WebRTC, Opus, FLAC, Lz4, etc.). There's no validation that these builds are reproducible or that dependency versions are pinned. Add a CI workflow to verify CMake builds succeed for all architectures and document exact dependency versions in app/jni/CMakeLists.txt and app/jni/tgvoip/CMakeLists.txt to prevent build failures from upstream changes.

• [ ] Create .github/workflows/jni-build-validation.yml to build all CMake targets (arm64-v8a, armeabi-v7a, x86_64)
• [ ] Add version pinning comments in app/jni/CMakeLists.txt, app/jni/tgvoip/CMakeLists.txt, and all BuildXxx.cmake files (e.g., BuildWebp.cmake, BuildOpus.cmake)
• [ ] Document in app/jni/README.md the exact commit hashes or version tags for each third-party dependency and how to update them safely

Create unit tests for JNI bridge layer (bridge.cpp/bridge.h)

The app/jni/bridge.cpp and bridge.h files appear to be the critical interface between Java and native C++ code, but there's no test coverage visible. Add JNI-specific unit tests to verify serialization/deserialization of data passed across the Java/C++ boundary, which is a common source of crashes in native Android apps.

• [ ] Create app/jni/test/bridge_test.cpp with Google Test framework to verify JNI method signatures match expectations
• [ ] Add tests for emoji.cpp (app/jni/emoji.cpp) emoji encoding/decoding to ensure proper Unicode handling across the JNI boundary
• [ ] Integrate these tests into the CMakeLists.txt build with a separate test target (e.g., 'tgx_jni_tests') that CI can run

Document and test multiple FFmpeg codec implementations in androidx-media JNI layer

The app/jni/third_party/androidx-media directory has three separate implementations (latest, legacy, lollipop) of ffmpeg_jni.cc, flac_jni.cc, and opus_jni.cc, but there's no documentation explaining when each is used, what the differences are, or how to ensure they're kept in sync. This creates maintenance debt and potential bugs.

• [ ] Create app/jni/third_party/androidx-media/README.md explaining the purpose of each version (latest/legacy/lollipop), which Android API levels they target, and what features differ
• [ ] Add a verification script (app/jni/third_party/androidx-media/verify_consistency.py) that checks all three implementations have the same public function signatures and flags mismatches in CI
• [ ] Create unit tests in app/jni/test/androidx_media_test.cpp that verify codec behavior is identical across all three implementations for common audio formats

• Add CMake build documentation for app/jni/third_party/androidx-media/jni.h integration: currently no comments explaining how JNI headers are versioned relative to androidx-media releases
• Create unit tests for app/jni/emoji.cpp emoji rendering edge cases (surrogate pairs, zero-width joiners, skin tone modifiers)—file exists but test coverage isn't visible
• Document VoIP codec selection logic in app/jni/tgvoip/BuildTgCalls.cmake—script chooses Opus vs. other codecs but decision criteria are implicit

The Telegram X Android codebase demonstrates moderate security posture with several concerns. The primary critical issue is the presence of exposed configuration files (google-services.json, agconnect-services.json) containing sensitive Firebase/Huawei credentials that must be removed immediately. The application's heavy reliance on multiple third-party native libraries (multimedia codecs, WebRTC) without visible version pinning creates dependency management risks and requires robust vulnerability tracking. The absence of visible dependency management files, SBOMs, and comprehensive security scanning practices weakens overall visibility into the security state. Strengths include use of

• High · Exposed Firebase Configuration Files — app/google-services.json, app/agconnect-services.json. The repository contains google-services.json and agconnect-services.json files in the app directory. These files typically contain sensitive Firebase and Huawei AGConnect configuration including API keys, project IDs, and service account information that should not be committed to version control. Fix: Remove these files from version control immediately using git rm --cached. Add them to .gitignore. Store them securely in a CI/CD secret management system or distribute them through secure channels outside the repository.
• Medium · Native Code Library Dependencies (JNI) — app/jni/CMakeLists.txt, app/jni/tgvoip/CMakeLists.txt, app/jni/BuildFlac.cmake, app/jni/BuildOpus.cmake, app/jni/BuildWebp.cmake, and related build files. The codebase includes multiple third-party native libraries via JNI (WebRTC, FFmpeg, Opus, Flac, WebP, etc.) without visible version pinning or dependency lock files. This increases the risk of using outdated or vulnerable versions of these critical libraries. Fix: Implement explicit version pinning for all third-party dependencies in CMake files. Maintain a dependency manifest documenting all native library versions. Regularly audit these dependencies for security vulnerabilities using tools like OWASP Dependency-Check adapted for C/C++ libraries.
• Medium · Multiple Codec and Media Processing Libraries — app/jni/third_party/androidx-media/*, app/jni/ build files for multimedia codecs. The application integrates numerous media processing libraries (FFmpeg, Flac, Opus, WebP, libyuv, OpenH264, RNNoise) that are commonly targeted for buffer overflow and memory corruption vulnerabilities. Multiple versions exist (legacy, lollipop, latest) which may introduce version inconsistencies. Fix: Implement address sanitizer (ASAN) and memory sanitizer testing for JNI code. Keep all media libraries updated to latest security patches. Consider using sandboxing techniques for media processing. Implement input validation for media file formats.
• Medium · Absence of Visible Dependency Management File — app/build.gradle.kts (content not provided). No build.gradle, build.gradle.kts, package.json, or pom.xml content was provided in the analysis. While app/build.gradle.kts exists, its contents are not visible, preventing assessment of Android Gradle dependencies for known vulnerabilities. Fix: Provide access to build configuration files for analysis. Implement dependency scanning in CI/CD pipeline using tools like Android Gradle vulnerability scanning. Use versions of libraries with known security patches. Implement software composition analysis (SCA) scanning.
• Low · Potential Information Disclosure via Repository Structure — app/jni/CMakeLists.txt, app/jni/tgvoip/CMakeLists.txt. The detailed file structure and comments in CMakeLists.txt files could reveal internal architecture and technology stack, aiding attackers in targeting specific known vulnerabilities. Fix: Review CMakeLists.txt files for unnecessary comments or verbose output. Ensure build systems don't expose detailed version information in release builds. Use security headers and obfuscation techniques in production builds.
• Low · Missing SBOM (Software Bill of Materials) — Repository root (absent). No visible Software Bill of Materials (SBOM) or dependency manifest is present in the repository, making it difficult to track and audit all third-party components for security vulnerabilities. Fix: Generate and maintain an SBOM using tools like CycloneDX or SPDX format. Include both native and Java dependencies. Update SBOM with each release. Publish SBOM for transparency and security auditing.

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.