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/tdlib/td 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 2d ago
• 3 active contributors
• BSL-1.0 licensed
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 98% of recent commits
• ⚠ Non-standard license (BSL-1.0) — review terms
• ⚠ 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 tdlib/td repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/tdlib/td.

What it runs against: a local clone of tdlib/td — 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 tdlib/td | Confirms the artifact applies here, not a fork | | 2 | License is still BSL-1.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

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

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

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

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

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
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/tdlib/td"
  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).

TDLib is a cross-platform C++ library that handles all the complexity of building Telegram clients—network protocols, MTProto encryption, local encrypted database storage, and message synchronization. It exposes a clean async JSON API so developers in any language (C++, Java, .NET, JavaScript, Python, PHP, etc.) can build Telegram apps without reimplementing cryptography or networking. Monolithic C++ library with platform-specific layers. Core logic in td/ (likely contains td_api, networking, crypto, database). Language bindings in example/ (example/cpp, example/android, example/web with tdweb JavaScript wrapper). Benchmark suite in benchmark/ for performance validation. Build system uses CMake with modular toolchain files (CMake/TdSetUp*.cmake) for compiler detection and platform setup.

Mobile and desktop app developers building Telegram clients on iOS, Android, Windows, macOS, Linux, WebAssembly, and other platforms. Also used by the Telegram Bot API backend (handles 25,000+ concurrent bots per instance). Contributors are mostly Telegram core team plus the open-source community extending language bindings.

Production-ready and actively maintained. 17M+ lines of C++ indicate a substantial, battle-tested codebase. Presence of comprehensive CMake build system, example applications, benchmarks (bench/ directory), and multi-language bindings (Java via JNI, .NET via C++/CLI, JavaScript/WebAssembly) confirm maturity. Used at scale in Telegram's own infrastructure.

Low risk for core functionality (proven in production), but moderate complexity risk: this is a large C++ project requiring C++17 compiler and careful platform-specific configuration (iOS.cmake, illumos.cmake, Android toolchain). Build system is CMake-heavy; cross-compiling for mobile platforms requires understanding CMake presets and platform-specific flags. Monolithic repo means changes to core TD can affect all language bindings.

Active development visible through comprehensive build infrastructure, recent SDK compatibility updates (watchOS, tvOS, visionOS, Tizen support listed), and ongoing JavaScript/WebAssembly work (example/web/tdweb with webpack/Babel tooling). CHANGELOG.md indicates regular releases. Platform coverage continues to expand.

git clone https://github.com/tdlib/td.git
cd td
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)

For JavaScript/web: cd example/web/tdweb && npm install && npm run build.

Daily commands: C++ example: example/cpp/ has CMakeLists.txt—build via CMake, executable links against libtdclient. JavaScript/Web: cd example/web/tdweb && npm start launches webpack-dev-server. Android: example/android/build-tdlib.sh cross-compiles; uses OpenSSL, Android NDK. iOS: uses iOS.cmake preset with Xcode toolchain.

• CMakeLists.txt: Root CMake configuration that orchestrates the entire build, detects C++17 support, includes platform-specific toolchain files
• CMake/TdSetUpCompiler.cmake: Central compiler detection and flag setup for all platforms (Linux, macOS, iOS, Android, Windows, etc.)
• td/generate/scheme/td_api.tl: Schema definition file that auto-generates the entire public C++ API; editing this regenerates td_api.h
• example/cpp/CMakeLists.txt: Simplest C++ example showing how external projects consume TDLib via find_package(Td) and link libtdclient
• example/android/CMakeLists.txt: Shows Android-specific build with NDK toolchain, OpenSSL integration, and JNI bridge setup
• example/web/tdweb/webpack.config.js: JavaScript/WebAssembly build; bundles TDLib compiled to WASM, uses broadcast-channel and localforage for storage
• benchmark/: Comprehensive performance benchmarks (crypto, DB, actor model, HTTP) used to validate library performance at scale
• TdConfig.cmake: CMake config file for downstream consumers; defines find_package() targets and link libraries

Core protocol/API changes: edit td/generate/scheme/td_api.tl, regenerate via generator tool. New platform: add CMake preset in CMake/ (cf. iOS.cmake, illumos.cmake), update platform detection in TdSetUpCompiler.cmake. Language binding: add code generation + binding layer (see Java JNI example in example/android/). Benchmark: add file to benchmark/ following naming bench_*.cpp, link in CMakeLists.txt. Documentation: update Doxyfile, inline C++ comments for td_api.h generation.

Cross-compilation complexity: Building for iOS/Android requires proper NDK/Xcode setup and custom CMake toolchain files; mismatched architectures (arm64 vs armv7) cause silent link failures. Schema regeneration: Modifying td_api.tl requires running the code generator (likely in td/generate/) which is not automatic in the CMake build. Encryption key requirement: Local data encrypted via user-provided key—forgetting to pass key to init() results in all stored data being inaccessible. Build directory pollution: In-source builds are prevented (PreventInSourceBuild.cmake); must use separate build/ directory. CMake version: Complex platform detection may require CMake 3.16+; older versions silently skip features.

• MTProto Protocol — Core transport protocol TDLib implements for secure Telegram communication; understanding handshake, session keys, and message encryption is essential for debugging network issues
• Actor Model (async concurrency) — TDLib uses an actor-based async architecture (seen in bench_actor.cpp) where requests don't block; understanding how actors dispatch tasks is key to using the async JSON API correctly
• End-to-End Encryption (Secrets API) — TDLib encrypts local database storage with user-provided keys; the Secrets API allows apps to store sensitive data encrypted at rest, critical for security compliance
• Scheme-Driven Code Generation (TL Schema) — The td_api.tl schema file auto-generates the entire public C++ API; modifying the schema regenerates all serialization/deserialization code, reducing manual boilerplate
• Cross-Platform CMake Toolchains — TDLib's iOS.cmake, Android toolchain integration, and compiler detection (TdSetUpCompiler.cmake) are sophisticated examples of multi-platform C++ build system design; understanding CMake presets and target properties is essential for porting to new platforms
• Asynchronous Request-Response with JSON — TDLib's public API is fully async: send a JSON request, receive responses/updates asynchronously; there is no blocking—understanding event loops and message queues is critical for correct client code
• Language Binding via JNI and C++/CLI — TDLib is C++ but accessed from Java (Android), C# (.NET), JavaScript (WebAssembly)—understanding the bridging layer (JNI for Android, Emscripten for WASM) helps debug interop issues and extend to new languages

• telegramdesktop/tdesktop — Official Telegram Desktop client—primary consumer and reference implementation of TDLib
• TelegramMessenger/Telegram-iOS — Official Telegram iOS app; uses TDLib for all Telegram protocol handling and local storage
• vysheng/tg — Alternative Telegram client library (tg-cli) using lower-level MTProto; TDLib is the officially maintained successor
• LonamiWebs/Telethon — Popular Python async Telegram client library; used for bots and automation where TDLib's C++ core would be overkill
• eternnoir/pyTelegramBotAPI — Lightweight Python Telegram Bot API wrapper; complements TDLib for bot-only use cases without client complexity

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 comprehensive benchmark test suite for WebAssembly builds

The repo has extensive C++ benchmarks in /benchmark but no WebAssembly-specific performance tests. Given that TDLib supports WebAssembly (mentioned in features), contributors should add benchmarks for tdweb (example/web/tdweb) measuring JS/WASM interop performance, worker thread overhead, and IndexedDB operations through localforage.

• [ ] Create benchmark/bench_wasm.js to measure tdweb initialization time, message send/receive latency, and memory usage
• [ ] Add benchmark test for BroadcastChannel communication overhead (listed as dependency)
• [ ] Create benchmark/bench_wasm_indexeddb.js to test localforage operations (DB read/write performance)
• [ ] Document results in benchmark/README.md with baseline metrics for future regression detection

Add platform-specific CI workflows for cross-platform builds

While the repo supports 13+ platforms (Android, iOS, Windows, macOS, Linux, FreeBSD, OpenBSD, NetBSD, illumos, WebAssembly, watchOS, tvOS, visionOS), there is no evidence of CI workflows validating builds on all target platforms. The CMake infrastructure exists (CMake/iOS.cmake, CMake/illumos.cmake, CMake/TdSetUpCompiler.cmake) but CI coverage is incomplete.

• [ ] Create .github/workflows/build-matrix.yml to test Linux, macOS, Windows builds using matrix strategy
• [ ] Add .github/workflows/build-ios.yml for iOS builds (reference example/ios/build.sh and CMake/iOS.cmake)
• [ ] Add .github/workflows/build-wasm.yml for WebAssembly/tdweb builds (reference example/web/tdweb build scripts)
• [ ] Include linking and runtime checks to catch cross-platform compilation issues early

Create typed TypeScript stubs for tdweb JavaScript interface

The example/web/tdweb package exports JavaScript but lacks TypeScript definitions. The package.json shows typescript as a devDependency and eslint-plugin-flowtype suggests type awareness, but there are no .d.ts files for the tdweb dist outputs or API contracts.

• [ ] Create example/web/tdweb/dist/tdweb.d.ts with types for TDLib client initialization, send() method, receive callbacks, and event emitters
• [ ] Add tsconfig.json to example/web/tdweb with declaration generation enabled (declaration: true)
• [ ] Document the JavaScript API interface in example/web/README.md with TypeScript usage examples
• [ ] Ensure 'types' field points to dist/tdweb.d.ts in example/web/tdweb/package.json for npm consumers

• Add missing unit tests for benchmark/bench_db.cpp coverage—currently only timing tests exist; add correctness tests for database encryption, key rotation, and data integrity.
• Document the schema generation workflow: create a guide explaining how to modify td_api.tl and regenerate the C++ API, including where the code generator binary is located and what cmake target rebuilds it.
• Extend example/cpp/README.md with a step-by-step guide for setting up TDLib on Windows with MSVC 2019+, including OpenSSL/vcpkg integration, since only Linux/macOS are clearly documented.

• High · Outdated and Vulnerable Dependencies — package.json - devDependencies and dependencies. Multiple npm dependencies in package.json have known vulnerabilities or are significantly outdated. Specifically: acorn@^6.4.1 (from 2020, known vulnerabilities), webpack@^4.44.1 (v4 is EOL, v5+ recommended), babel-eslint@^10.0.1 (deprecated, should use @babel/eslint-parser), and eslint@^5.16.0 (from 2019, multiple CVEs). The uuid@^3.3.2 package is also outdated and should be upgraded to v9.x. Fix: Update all dependencies to latest stable versions: acorn to ^8.x, webpack to ^5.x or ^6.x, eslint to ^8.x or ^9.x, replace babel-eslint with @babel/eslint-parser, and upgrade uuid to ^9.x. Run 'npm audit' and address all reported vulnerabilities.
• High · Missing Security Headers Configuration — example/web/tdweb/webpack.config.json and package.json build scripts. The webpack configuration (referenced but not fully shown) and webpack-dev-server lack explicit security header configurations. The dev server configuration in 'start' script shows potential CORS and content security policy misconfigurations. Fix: Configure webpack-dev-server with appropriate security headers (Content-Security-Policy, X-Content-Type-Options, X-Frame-Options). Add CORS restrictions and implement proper origin validation.
• Medium · Husky and Lint-Staged Configuration Issues — package.json - husky and lint-staged sections. The husky and lint-staged configuration uses deprecated syntax ('linters' object is deprecated, should use 'lint-staged' directly). This may bypass pre-commit security checks in newer versions. Fix: Update husky configuration to v8+ syntax and modernize lint-staged configuration. Use direct lint-staged object format instead of nested 'linters' object.
• Medium · Incomplete Babel Configuration — package.json - babel section. The babel configuration in package.json appears truncated/incomplete ('"plugins"' is cut off). This may indicate incomplete security-critical build configuration or could lead to unexpected transpilation behavior. Fix: Complete the babel configuration, ensure all required plugins are explicitly listed, and validate the configuration syntax. Include @babel/plugin-transform-runtime in production builds for security.
• Medium · Broadcast Channel Library Usage Risk — package.json - dependencies section. The broadcast-channel@^2.1.12 dependency is outdated (v2 from 2019). This library handles cross-tab communication and could have security implications if not kept current, especially for handling sensitive data like authentication tokens. Fix: Upgrade broadcast-channel to the latest v5.x or v6.x version. Review how broadcast-channel is used in source code to ensure sensitive data is not transmitted through broadcast channels.
• Medium · LocalForage Storage Security Considerations — package.json - dependencies section, example/web/tdweb source code. The localforage@^1.7.3 dependency is significantly outdated (2019). LocalForage is used for client-side storage and may have security vulnerabilities when storing sensitive data. No encryption is visible in the dependency list. Fix: Upgrade localforage to the latest version. Implement encryption for sensitive data stored locally. Audit how authentication tokens and user data are stored and retrieved.
• Low · Missing Security Documentation — Repository root. No SECURITY.md or security policy document is visible in the repository structure. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file with responsible disclosure guidelines, security contact information, and known vulnerability reporting procedures.
• Low · Webpack Dev Server Exposure Risk — package.json - scripts.start. The 'start' script uses webpack-dev-server with --open flag which automatically opens the browser. In development environments, this could expose the application to unintended network access without explicit security configuration. Fix: Add explicit host and port binding in webpack-dev-server configuration (localhost only). Remove or conditionally use --open flag. Document security requirements for development environment setup

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.