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/overtake/TelegramSwift 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 — Slowing — last commit 8mo ago

• Last commit 8mo ago
• GPL-2.0 licensed
• ⚠ Slowing — last commit 8mo ago
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ GPL-2.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 overtake/TelegramSwift repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/overtake/TelegramSwift.

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

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-2.0" \\
  || miss "license drift — was GPL-2.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"

# 4. Critical files exist
test -f "Telegram-Mac/AppDelegate.swift" \\
  && ok "Telegram-Mac/AppDelegate.swift" \\
  || miss "missing critical file: Telegram-Mac/AppDelegate.swift"
test -f "Telegram-Mac/ApplicationContext.swift" \\
  && ok "Telegram-Mac/ApplicationContext.swift" \\
  || miss "missing critical file: Telegram-Mac/ApplicationContext.swift"
test -f "Telegram-Mac/AccountContext.swift" \\
  && ok "Telegram-Mac/AccountContext.swift" \\
  || miss "missing critical file: Telegram-Mac/AccountContext.swift"
test -f "Telegram-Mac/Appearance.swift" \\
  && ok "Telegram-Mac/Appearance.swift" \\
  || miss "missing critical file: Telegram-Mac/Appearance.swift"
test -f "Telegram-Mac.xcworkspace/xcshareddata/swiftpm/Package.resolved" \\
  && ok "Telegram-Mac.xcworkspace/xcshareddata/swiftpm/Package.resolved" \\
  || miss "missing critical file: Telegram-Mac.xcworkspace/xcshareddata/swiftpm/Package.resolved"

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

TelegramSwift is the official source code for Telegram macOS client, written in Swift 5.0 and C/C++ for performance-critical networking and media handling. It provides a native desktop messaging experience with end-to-end encryption, voice/video calls, file sharing, and animated sticker rendering, implementing the full Telegram API protocol stack. Single monolithic Xcode workspace (Telegram-Mac.xcworkspace) containing the main Telegram-Mac app target and FocusIntents extension. Core app logic resides in ~2000+ Swift files under Telegram-Mac/ directory following feature-based organization (AccountViewController, AddContactModalController, ArchiveSettingsController, etc.) with UI controllers paired to model/item classes. TDLib C++/C bindings handle MTProto protocol and data persistence; native Swift wraps high-level app state in AccountContext and ApplicationContext.

macOS users who want secure, fast messaging with no ads or middlemen; developers maintaining or contributing to the Telegram desktop ecosystem on macOS; security researchers auditing open-source encrypted communications.

This is production-ready, actively maintained software: it's the official Telegram client with millions of macOS users via Mac App Store (ID 747648890). The repo shows consistent development patterns, comprehensive CI via GitLab, and production-grade code structure. However, commit recency data isn't visible in this snapshot—check git log to assess current maintenance velocity.

The codebase is large (~23.7M lines Swift, ~11.5M C) with multiple language interop layers (Swift-C-C++ boundary in TDLib networking), increasing complexity and potential for memory safety issues in legacy C code. Dependencies span cryptographic libraries and media codecs; TDLib is a critical internal dependency. Single repository concentration for the entire macOS app means a major security issue affects the main client. Verify API stability with TDLib and check open issues at bugs.telegram.org before planning large changes.

The codebase shows active development: FocusIntents extension for macOS Focus Mode integration, AppIntents framework adoption for Siri shortcuts (AppIntentDataModel.swift, AppIntentsData.swift), animated sticker improvements (AnimatedStickerUtils.swift), and app appearance/theming work (AppAppearanceViewController.swift, Appearance.swift). Beta channel at t.me/macswift suggests ongoing feature testing.

1. Clone with submodules: git clone --recurse-submodules https://github.com/overtake/TelegramSwift.git (submodules include TDLib C++ bridge). 2. Open workspace: open Telegram-Mac.xcworkspace (NOT .xcodeproj—workspace includes dependent frameworks). 3. Ensure Xcode 12+ with Swift 5.0 toolchain. 4. Obtain your own Telegram API ID from https://core.telegram.org/api/obtaining_api_id (required; never use the production ID). 5. Build target 'Telegram-Mac' for Release or Debug.

Daily commands: Command-line build: xcodebuild -workspace Telegram-Mac.xcworkspace -scheme 'Telegram-Mac' -configuration Release build. Or use Xcode IDE: Cmd+B to build, Cmd+R to run. For debugging, attach to the macOS target in Xcode's debugger (Cmd+Y after launch). Beta builds: check .gitlab-ci.yml for CI/CD pipeline commands and signing certificates.

• Telegram-Mac/AppDelegate.swift — Application entry point and lifecycle management; defines window setup, notification handling, and app initialization for macOS.
• Telegram-Mac/ApplicationContext.swift — Core application context singleton managing state, account contexts, and global app-level services; foundational to all feature layers.
• Telegram-Mac/AccountContext.swift — Per-account context encapsulating user state, API interactions, and account-specific services; required for multi-account architecture.
• Telegram-Mac/Appearance.swift — Theme and appearance system managing dark/light mode, colors, and UI styling across the entire application.
• Telegram-Mac.xcworkspace/xcshareddata/swiftpm/Package.resolved — Swift Package Manager dependency lock file; controls all external framework versions and build reproducibility.
• Telegram-Mac/AccountViewController.swift — Primary account UI container and navigation controller; orchestrates main chat list, conversation views, and account switching.
• Telegram-Mac/AddReactionManager.swift — Reaction system manager; handles emoji reactions on messages, core to chat interactivity.

Add a New Settings Screen

1. Create a new view controller inheriting from ViewController or a similar base class (Telegram-Mac/ArchiveSettingsController.swift)
2. Define UI items and table rows for settings display, following the pattern in AccentColorRowItem or AppearanceMoreItem (Telegram-Mac/AccentColorRowItem.swift)
3. Register the controller in AccountViewController's navigation/menu system (Telegram-Mac/AccountViewController.swift)
4. Apply theme via Appearance singleton to ensure dark/light mode consistency (Telegram-Mac/Appearance.swift)

Add a New Message Feature (e.g., Sticker Pack Support)

1. Create a manager class following AddReactionManager or AnimatedStickerUtils pattern (Telegram-Mac/AddReactionManager.swift)
2. Create UI item components for the feature (e.g., headers, selection panels) (Telegram-Mac/AnimtedStickerHeaderItem.swift)
3. Integrate with AccountContext to manage feature state and API calls (Telegram-Mac/AccountContext.swift)
4. Register feature in chat view controllers and message UI (Telegram-Mac/AccountViewController.swift)

Add Siri Shortcut or Focus Mode Support

1. Define intent class in AppIntentsData.swift following AppIntent protocol (Telegram-Mac/AppIntentsData.swift)
2. Create corresponding intent handler in AppIntentDataModel or new model file (Telegram-Mac/AppIntentDataModel.swift)
3. For focus modes, extend FocusIntents.swift with new intent definitions (FocusIntents/FocusIntents.swift)
4. Implement FocusIntentsExtension.swift to handle focus mode changes (FocusIntents/FocusIntentsExtension.swift)

Add a New Modal Dialog or Contact Feature

1. Create modal controller following AddContactModalController pattern (Telegram-Mac/AddContactModalController.swift)
2. Create associated table items if needed (see AddContactTableItem) (Telegram-Mac/AddContactTableItem.swift)
3. Wire modal launch into AccountViewController or appropriate parent controller (Telegram-Mac/AccountViewController.swift)
4. Apply Appearance theme to ensure UI consistency (Telegram-Mac/Appearance.swift)

• Swift 5.0 + macOS native APIs — Official Telegram client requires native performance, full OS integration (notifications, system menu, drag-drop), and tight control over memory/rendering for responsive chat UI.
• Xcworkspace + SPM (Swift Package Manager) — Manages multi-framework architecture (app + extensions like FocusIntents) and external dependencies reproducibly across team and CI/CD.
• TDLib (Telegram Database Library) backend — Provides official Telegram protocol implementation, local database, offline support, and sync logic—abstracted behind AccountContext API.
• Multi-account architecture (AccountContext per user) — Telegram's core feature; each account is stateless wrt others, allowing simultaneous logins and clean separation of user data.
• Appearance singleton for theme management — macOS 10.14+ requires theme-aware UI; centralized Appearance ensures consistent dark/light mode across 600 files and 100+ view controllers.

• Native macOS client vs. web or cross-platform

  • Why: macOS users expect native apps with system integration (Dock, menu bar, keyboard shortcuts, system notifications). Web would be lower maintenance but worse UX.
  • Consequence: High maintenance burden (600 files); tight coupling to macOS APIs; slower to add features compared to web version.

• TDLib backend abstraction hidden in AccountContext

  • Why: Decouples UI from protocol details; enables testing and protocol upgrades without rewriting every controller.
  • Consequence: Extra indirection and data copying; TDLib's async callback model requires careful state management to avoid race conditions.

• Single Appearance singleton instead of SwiftUI environment

  • Why: undefined
  • Consequence: undefined

1. Submodules required: Cloning without --recurse-submodules leaves TDLib bridge code missing; builds will fail. 2. API ID mandatory: Hardcoded production API ID in repo won't work for forked builds; you must obtain your own from core.telegram.org. 3. Workspace, not project: Opening Telegram-Mac.xcodeproj directly bypasses framework linking; always use Telegram-Mac.xcworkspace. 4. macOS version constraints: Minimum deployment target is likely macOS 10.12+; check Xcode build settings for exact floor. 5. Code signing: Mac App Store and non-MAS versions have different provisioning profiles and entitlements; beta builds use separate certificate chains (see .gitlab-ci.yml). 6. TDLib binary bloat: C++ TDLib compiled for multiple architectures (arm64 + x86_64) can make builds slow and binaries large.

• MTProto v2 Protocol — TDLib abstracts MTProto v2 in this codebase, but understanding the binary framing, encryption, and session key negotiation explains why TDLib is trusted with sensitive auth tokens
• TDLib (Telegram Database Library) — Core networking and persistence layer in this macOS client; a C++ library wrapping MTProto, database, and state management—critical to understand for networking or sync issues
• AppKit View Lifecycle & Responder Chain — Telegram-Mac uses macOS AppKit (not SwiftUI), so understanding NSViewController, NSTableView, and the responder chain is essential for UI work and event handling
• TGS (Telegram Sticker Format) — Custom lottie-based animation format used by Telegram; AnimatedStickerUtils.swift decodes and renders TGS via Metal—relevant for media handling and performance optimization
• Metal Graphics Framework — Used for GPU-accelerated sticker and media rendering in Telegram-Mac; shaders in GLSL provide high-performance animation without CPU overhead
• macOS Focus Intents & Siri Shortcuts — FocusIntents extension allows Siri integration and Focus Mode rules; AppIntents framework is modern replacement for Siri Shortcuts—understanding this enables voice control and automation features
• Code Signing & Provisioning Profiles (Apple) — Telegram-Mac must be signed differently for Mac App Store vs. non-MAS distribution; .gitlab-ci.yml shows certificate pinning and entitlements handling—critical for CI/CD and distribution

• telegramdesktop/tdesktop — Official Telegram desktop client for Windows/Linux in C++; shares protocol implementation and can be referenced for cross-platform MTProto behavior
• TelegramMessenger/Telegram-iOS — Official Telegram for iOS in Swift; similar UI patterns and AccountContext architecture; useful for understanding platform-agnostic business logic
• tdlib/td — Official TDLib repository (C++ library used by this macOS client); source of protocol implementation and database layer; required for understanding networking stack
• apple/swift-nio — Low-level networking library; potential alternative for future async/await networking refactors in macOS Telegram
• realm/realm-swift — Persistent storage framework used in some Telegram Swift forks; relevant if considering migration from TDLib-managed storage

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 unit tests for AccountContext.swift and AccountUtils.swift

The repo has core account management files (AccountContext.swift, AccountUtils.swift, AccountViewController.swift) but no visible test targets. These handle critical authentication and user account state. Adding XCTest unit tests would improve reliability and make refactoring safer for future contributors.

• [ ] Create Telegram-MacTests target if it doesn't exist
• [ ] Write tests for AccountUtils.swift covering account validation, persistence, and utility functions
• [ ] Write tests for AccountContext.swift covering account state management and lifecycle
• [ ] Add tests to CI pipeline (update .gitlab-ci.yml to run tests on commits)

Add GitHub Actions CI workflow for Swift build validation

The repo uses GitLab CI (.gitlab-ci.yml) but no GitHub Actions workflow exists. Since the repo is hosted on GitHub (overtake/TelegramSwift), adding a GitHub Actions workflow for Swift compilation and basic linting would improve visibility and catch issues faster for GitHub users and contributors.

• [ ] Create .github/workflows/swift-build.yml with macOS runner
• [ ] Configure workflow to run 'xcodebuild build' on Telegram-Mac.xcworkspace
• [ ] Add SwiftLint validation step to check code style
• [ ] Trigger on pull requests and pushes to main branch

Document FocusIntents extension architecture and setup requirements

The FocusIntents directory contains an App Intent extension (FocusIntents.swift, FocusIntentsExtension.swift) with entitlements but lacks documentation. New contributors won't understand how to build/test this extension or integrate new Focus modes. A dedicated FOCUS_INTENTS.md would explain the purpose, build steps, and how to extend it.

• [ ] Create FocusIntents/README.md documenting the extension's purpose (macOS Focus modes integration)
• [ ] Document required entitlements from FocusIntents.entitlements and why they're needed
• [ ] Add step-by-step guide for building just the FocusIntents target
• [ ] Include examples of how to add new Focus-related intents to FocusIntents.swift

• Add missing test coverage for AccountUtils.swift: This file (visible in file list) likely contains helper logic for account management but has no corresponding _Tests.swift file in the repo structure. Adding unit tests for account state transitions would improve reliability.
• Improve AnimatedStickerUtils.swift documentation: The sticker rendering pipeline mixes Metal shaders, GLSL, and C++ decoders. Add inline comments explaining the TGS → Metal texture flow and shader compilation pipeline for future maintainers.
• Create a developer guide for Context patterns: AccountContext and ApplicationContext are central but undocumented. Write a Markdown guide (CONTEXT_ARCHITECTURE.md) explaining when to use each, how to subscribe to state changes, and the reactive update flow—reduce onboarding time for new contributors.

The Telegram macOS codebase shows moderate security posture. No critical vulnerabilities were identified from the visible file structure; however, several medium-severity concerns exist: incomplete dependency visibility, potential credential exposure in configuration files, and CI/CD pipeline configuration not reviewed. The project appears well-structured with appropriate use of entitlements and build configuration, but critical security practices around secret management and dependency auditing cannot be fully assessed without viewing actual file contents (Package.swift, .gitignore details, source code patterns, and CI/CD configuration). Recommendation: implement strict secret management practices, conduct a comprehensive dependency audit, and ensure all configuration files exclude sensitive data.

• Medium · Incomplete Dependency Visibility — Telegram-Mac.xcworkspace/xcshareddata/swiftpm/Package.resolved. The Package.resolved file is present but no complete dependency manifest (Package.swift, Podfile, Cartfile, etc.) is visible in the provided file structure. This makes it impossible to assess whether the project uses outdated, vulnerable, or unmaintained dependencies. Fix: Ensure all dependencies are listed in a version-controlled package manifest. Regularly audit dependencies using tools like SwiftPM audit, and keep all packages updated to their latest secure versions.
• Medium · Potential Hardcoded Credentials in Configuration Files — FocusIntents/FocusIntents.entitlements, FocusIntents/Info.plist, Telegram-Mac.xcworkspace/xcshareddata/WorkspaceSettings.xcsettings. Configuration files such as Info.plist, XCWorkspace settings, and entitlements files (.entitlements) are present. These files may contain sensitive information like API keys, tokens, or provisioning details if not properly managed. Fix: Never commit sensitive credentials to version control. Use environment variables, secure build configurations, or secret management tools. Ensure .entitlements and plist files do not contain API keys or tokens. Implement pre-commit hooks to prevent accidental credential leaks.
• Low · Missing .gitignore Coverage for Sensitive Build Artifacts — .gitignore. While a .gitignore file exists, the content is not provided. Build artifacts, derived data, and configuration files specific to developer machines may inadvertently be committed. Fix: Ensure .gitignore comprehensively covers: build directories, Xcode derived data, .xcworkspace/xcuserdata/, user-specific scheme files, CocoaPods/SPM artifacts, and any auto-generated configuration files containing credentials.
• Low · Submodule Dependency Management — .gitmodules. A .gitmodules file is present, indicating the project uses Git submodules. Submodules can introduce supply chain risks if not properly pinned to secure commits and regularly audited. Fix: Pin all submodules to specific, vetted commit hashes. Regularly audit submodule sources for security updates. Document the purpose and maintenance status of each submodule. Consider using package managers (Swift PM, CocoaPods) for better vulnerability tracking.
• Medium · CI/CD Pipeline Security Configuration Not Visible — .gitlab-ci.yml. A .gitlab-ci.yml file is present, indicating GitLab CI/CD usage. The configuration is not provided for review, but typical CI/CD risks include: insecure secret handling, uncontrolled artifact storage, or insufficient access controls. Fix: Review CI/CD pipeline configuration to ensure: secrets are managed via GitLab CI/CD variables (not committed), build artifacts are signed, access controls limit who can trigger deployments, and audit logging is enabled. Use protected branches for sensitive operations.

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.