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/UnigramDev/Unigram 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 — Solo project — review before adopting

• Last commit 1d ago
• GPL-3.0 licensed
• ⚠ Solo or near-solo (1 contributor active in 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 UnigramDev/Unigram repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/UnigramDev/Unigram.

What it runs against: a local clone of UnigramDev/Unigram — 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 UnigramDev/Unigram | 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 develop exists | Catches branch renames | | 4 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "UnigramDev/Unigram(\\.git)?\\b" \\
  && ok "origin remote is UnigramDev/Unigram" \\
  || miss "origin remote is not UnigramDev/Unigram (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 develop >/dev/null 2>&1 \\
  && ok "default branch develop exists" \\
  || miss "default branch develop 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 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
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/UnigramDev/Unigram"
  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).

Unigram is a native Windows Telegram client written primarily in C# that provides a full-featured desktop experience for Telegram messaging. It wraps TDLib (Telegram Database library) via C++/C bindings and delivers features like chat management, media handling, and real-time messaging through a WinUI/XAML-based UI, offering an alternative to the official Telegram desktop client for Windows users. Monorepo structure: Telegram/ directory contains the main WinUI/XAML frontend in C#; Libraries/ contains vendored C++ code including libtextclassifier (language detection) and TDLib bindings; Documentation/ holds build and usage guides; Build.ps1 orchestrates the PowerShell-based build pipeline. State management and API bindings live in the main C# project rather than separate packages.

Windows users seeking a lightweight, feature-rich Telegram client alternative; C# developers contributing to cross-platform Telegram ecosystem projects; Windows app developers building on TDLib integration patterns.

Production-ready: actively developed with regular releases shipped to Microsoft Store (app ID 9n97zckpd60q) and beta channel via t.me/unigramappx. The project maintains comprehensive documentation (Build-instructions.md, Shortcuts.md, TDLib-logs.md) and 28 built-in languages, indicating mature localization infrastructure. Recent activity visible through changelog and release section suggests active maintenance, though specific commit recency data is not in the file listing provided.

Moderate risk: depends on external TDLib library (C++ component in /Libraries/) which requires compilation on build, adding complexity to contributor onboarding. Single-team maintenance by UnigramDev (evident from repo name structure) creates concentration risk. The large C++ dependency footprint (1.29M LOC in Libraries/libtextclassifier/ for language identification alone) increases surface area for bugs, though this is vendored code rather than external dependency.

Active maintenance evident from CHANGELOG.md and releases section; ongoing localization updates via Telegram translations platform (28 languages supported); beta builds distributed through Telegram's t.me/unigramappx channel with new features and bug fixes; specific recent PRs/milestones not visible in provided file listing but contributing guidelines suggest structured development process.

Clone the repo: git clone https://github.com/UnigramDev/Unigram.git && cd Unigram. Install dependencies and build: powershell -ExecutionPolicy Bypass -File Build.ps1 (requires PowerShell build script at repository root). Follow detailed instructions in Documentation/Build-instructions.md for environment setup, including Visual Studio 2022 and Windows SDK prerequisites.

Daily commands: After building with Build.ps1, launch the compiled .msixbundle or .appx from build output directory. For development: open Telegram.sln (primary VS solution) in Visual Studio 2022, build solution, run the Telegram project. Debug symbols and TDLib logging available via Documentation/TDLib-logs.md.

• Build.ps1: Master build orchestration script that compiles C++ components and produces final .msixbundle/.appx packages for distribution
• Documentation/Build-instructions.md: Essential setup guide covering Visual Studio configuration, SDK versions, TDLib compilation, and Windows environment prerequisites
• Libraries/libtextclassifier/: Vendored language identification ML model (1.29M LOC); critical for chat/message classification and language-specific features
• CONTRIBUTING.md: Governance document explaining contribution workflow, feature request process via bugs.telegram.org, and code standards
• Telegram/ (main project root): Core WinUI/C# application code containing UI views, ViewModels, and Telegram protocol integration logic
• .vsconfig: Visual Studio workload configuration file specifying required components (.NET, C++ toolsets, Windows SDK) for build environment

UI changes: modify XAML files and C# ViewModels in main Telegram/ project directories (structure follows typical WinUI conventions: Views/, ViewModels/, Models/). TDLib integration: examine C++ interop layer (likely in Telegram/obj or wrapper classes). Localization: contribute via https://translations.telegram.org/en/Unigram. Bug reports/features: file at https://bugs.telegram.org/ per CONTRIBUTING.md. For new features, read CONTRIBUTING.md first to understand approval process.

TDLib C++ library must compile successfully before C# layers can function—missing Windows SDK or C++ build tools will fail silently in some cases. The libtextclassifier/ directory is a massive vendored dependency (not a submodule) that significantly increases clone size and build time. Build.ps1 requires unrestricted PowerShell execution policy; some corporate environments block this. Windows 10 N requires explicit Media Feature Pack installation (noted in README but easy to miss). Telegram API key/testing infrastructure not documented in repository—contributors may assume it's included but actual Telegram server communication requires valid credentials.

• TDLib (Telegram Database Library) — Core abstraction layer Unigram depends on for all Telegram API communication, authentication, and account state—understanding its async callback model is essential for debugging message delivery, user sync, and connection issues
• P/Invoke and C# Interop — Unigram marshals data between C# managed code and C++ TDLib via P/Invoke declarations; incorrect marshaling causes memory leaks and crashes, so contributors must understand SafeHandle, MarshalAs attributes, and struct layout rules
• WinUI 3 / XAML Data Binding — Unigram's entire UI is built on WinUI 3 XAML with data binding to C# ViewModels; understanding binding modes, dependency properties, and XAML markup is prerequisite for any UI feature work
• Language Identification via ML (libtextclassifier) — The vendored libtextclassifier library performs language detection on messages for auto-translation and keyboard selection; understanding flatbuffers schema (embedding-network.fbs) helps debug language-specific edge cases
• MSIX / AppX Packaging for Windows Store — Unigram distributes via Microsoft Store using .msixbundle format; contributors must understand Store certification rules, manifest configuration, and versioning to avoid deployment failures
• MVVM Pattern (Model-View-ViewModel) — Standard WinUI architectural pattern used throughout Unigram; separation of UI (XAML Views), presentation logic (ViewModels), and data (Models) is critical for maintainability and testability
• Flatbuffers Serialization — libtextclassifier uses flatbuffers for efficient ML model serialization (model.fbs, embedding-network.fbs); understanding the schema helps optimize message processing and debug model loading failures

• tdlib/td — Official TDLib repository—the core C++ library that Unigram wraps; essential for understanding protocol layer and filing upstream bugs
• microsoft/winui-3 — WinUI 3 framework that powers Unigram's entire UI layer; reference for XAML patterns, control behavior, and platform-specific APIs
• telegramdesktop/tdesktop — Official Telegram Desktop client (C++ reference implementation); design patterns, feature parity discussions, and protocol edge cases
• X1r0z/ActiveMQ-RCE — Not related—ignore if encountered; verify only tdlib/td, microsoft/winui-3, and telegramdesktop/tdesktop for Telegram Windows ecosystem

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 build verification GitHub Actions workflow

The repo has a Build.ps1 script and build instructions in Documentation/Build-instructions.md, but there's no CI pipeline to automatically verify builds on pull requests. This is critical for a Windows desktop application where build breaks can slip through. A GitHub Actions workflow would validate that PRs don't break the build process before merge.

• [ ] Create .github/workflows/build-verification.yml that runs Build.ps1 on Windows runner for PRs
• [ ] Reference Documentation/Build-instructions.md to ensure all build prerequisites are installed in the workflow
• [ ] Add build artifact upload for successful builds to enable quick testing of PRs
• [ ] Document the workflow in Documentation/Build-instructions.md with a CI section

Document TDLib integration architecture and add integration tests

The repo includes comprehensive TDLib binding code (Libraries/libtextclassifier and numerous language ID utilities), but there's only a TDLib-logs.md file in Documentation/. New contributors need clear documentation on how TDLib is integrated, how to update it, and how to test Telegram API interactions. This would include integration test examples.

• [ ] Create Documentation/TDLib-integration.md explaining the TDLib wrapper architecture and version management
• [ ] Document the libtextclassifier library purpose and how it's used (language detection for messages)
• [ ] Create a sample integration test in a new Tests/ directory showing how to test TDLib API calls
• [ ] Add instructions for updating TDLib version with verification steps

Add unit tests for Unigram.Native language identification module

The Libraries/libtextclassifier directory contains substantial C++ code for language identification (embedding networks, feature extractors, FEL parsing), but there are no visible unit tests in the repository structure. Given the complexity of NLP/ML code, adding focused unit tests for core modules (embedding-network.cc, feature-extractors, model loading) would prevent regressions and make the codebase more maintainable for contributors.

• [ ] Create Tests/Unigram.Native.Tests/ directory with CMake or MSBuild configuration
• [ ] Add tests for Libraries/libtextclassifier/lang_id/common/embedding-network.cc covering initialization and forward pass
• [ ] Add tests for Libraries/libtextclassifier/lang_id/common/fel/feature-extractor.cc with sample text inputs
• [ ] Add tests for model loading/parsing (flatbuffers/model-utils.cc) to catch format regressions
• [ ] Document test execution in Documentation/Build-instructions.md

• Add unit tests for C# interop layer marshaling between TDLib C++ and managed code (currently no test/ directory visible; starting with simple P/Invoke validation tests would improve reliability and onboard contributors to architecture)
• Expand Documentation/TDLib-logs.md with concrete examples of parsing TDLib debug output and troubleshooting common connection failures (currently minimal; real examples from GitHub issues would help contributors debug integration problems)
• Create a Contributor's Architecture Guide documenting MVVM structure, state management patterns, and TDLib binding flows (missing from /Documentation/; would significantly reduce onboarding friction for new C# contributors unfamiliar with WinUI)

The Unigram Telegram client codebase appears to be an active Windows application project with moderate security posture. Key concerns include: (1) third-party native library (libtextclassifier) dependency management visibility; (2) potential memory safety issues in C/C++ components without visible hardening measures; (3) Flatbuffers deserialization without apparent validation; (4) absence of a security reporting policy. The project demonstrates good practices with open-source transparency and contribution guidelines, but requires enhanced security tooling for native code analysis and dependency monitoring. Recommended improvements: implement automated SAST/DAST scanning, establish dependency vulnerability tracking, conduct security code review of C++ components, and publish a security policy.

• Medium · Third-party Library Integration Without Visible Dependency Management — Libraries/libtextclassifier/. The codebase includes libtextclassifier library with multiple compiled components (embedding networks, language identification models). No visible package management file (nuspec, packages.config, .csproj with package references) was provided to assess dependency versions and known vulnerabilities. Fix: Provide dependency files for analysis. Implement automated dependency scanning using tools like OWASP Dependency-Check, NuGet audit, or Snyk. Regularly update third-party libraries and monitor for CVEs.
• Medium · Native Code Components Without Visible Security Hardening — Libraries/libtextclassifier/lang_id/common/file/ and related C++ components. The libtextclassifier library contains C/C++ code with memory management operations (mmap, file operations, embedding networks). Without visible security configurations or compiler flags, potential memory safety issues may exist. Fix: Apply modern C++ security practices: use Address Sanitizer (ASan), enable stack canaries, use Position Independent Executables (PIE). Review memory allocation patterns for buffer overflows and use-after-free vulnerabilities. Consider using memory-safe languages or strict bounds checking.
• Medium · Flatbuffers Schema Without Validation Configuration — Libraries/libtextclassifier/lang_id/common/flatbuffers/. Flatbuffers are used for data serialization (embedding-network.fbs, model.fbs). Deserializing untrusted data without proper validation could lead to buffer overflows or denial of service attacks. Fix: Implement strict schema validation. Validate buffer sizes before deserialization. Set maximum limits on data sizes. Use Flatbuffers with size_prefixed buffers. Add bounds checking in generated code.
• Low · Build Script Without Visible Security Checks — Build.ps1. Build.ps1 PowerShell script exists but content is not provided. PowerShell scripts can execute arbitrary code and may have privilege escalation risks if not properly secured. Fix: Review Build.ps1 for: execution policy, proper error handling, input validation, no hardcoded credentials, code signing, and secure script execution context. Consider using signed scripts with code signing certificates.
• Low · Missing Security Documentation — Repository root. While CONTRIBUTING.md and CODE_OF_CONDUCT.md exist, no visible SECURITY.md file for reporting vulnerabilities responsibly. This may hinder coordinated vulnerability disclosure. Fix: Create a SECURITY.md file with: vulnerability reporting process, responsible disclosure policy, PGP key for encrypted submissions, and expected response timeline. Follow GitHub security policy best practices.
• Low · Incomplete Repository Analysis — Global. Dependency package file content is empty and actual application code (Telegram project files) is not provided in the file listing. Full security analysis is limited. Fix: Provide complete dependency files (.csproj, packages.config, or .nuspec), NuGet dependencies, and actual application source code for comprehensive security analysis.

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.