Skip to content
iebbPublic

About

A Telegram client, but déjà vu

Resources

Stars

703 stars

Watchers

2 watching

Forks

Latest commit

 

History

1,959 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Mithka

Mithka — an independent Telegram client

English | 简体中文

Mithka is a fast, compact, cross-platform Telegram client built with Flutter and TDLib over Dart FFI. It runs natively on Android, iOS, macOS, Windows, Linux, and HarmonyOS Next—adapting from single-hand phone navigation to multi-pane tablet and desktop workspaces.

Mithka desktop, iPad, and iPhone Duo layout mockups

Illustrative layout previews using fictional conversations. Device frames are mockups rather than live screenshots.

Important

Mithka is an independent, unofficial project. It is not affiliated with, endorsed by, or connected to Telegram. “Telegram” is a trademark of its respective owner.

Mithka is also not affiliated with, endorsed by, sponsored by, or otherwise connected to Tencent or QQ. It does not use, include, copy, or redistribute proprietary QQ assets. “Tencent,” “QQ,” and their related trademarks and assets belong to their respective owners.

When building from source, Mithka connects to Telegram through TDLib using API credentials that you provide. Use it in accordance with Telegram’s Terms of Service and API Terms.


Downloads

Platform Beta / Nightly Stable
Android Google Play Open testing · GitHub APKs Google Play · GitHub release
iOS & iPadOS TestFlight App Store
macOS 12+ (arm64, x64) TestFlight · GitHub prereleases Mac App Store · GitHub release
Windows (x64, arm64) GitHub prereleases Latest GitHub release
Linux (x64, arm64) GitHub prereleases Latest GitHub release
HarmonyOS Next (.hap) GitHub prereleases Latest GitHub release

iPhone, iPad, and Mac share one App Store listing, and the TestFlight link covers all three.

Desktop packaging notes

  • macOS: The Mac App Store build is the recommended install; it updates through the App Store. The GitHub release also ships per-architecture .zip archives. They are ad-hoc signed and not notarized, so macOS asks you to approve the first launch in System Settings → Privacy & Security.
  • Windows ships both per-user setup.exe installers (no administrator rights required; registers Start Menu shortcuts and Installed Apps) and portable ZIP archives for x64 and arm64.
  • Linux ships x64 and arm64 AppImages alongside portable tarballs, validated in CI against Ubuntu 24.04 (chmod +x Mithka.AppImage and run from a writable directory).
  • Self-updates on Windows & Linux: Settings → About → Check for Updates fetches the latest stable GitHub release for your CPU architecture, verifies its published SHA-256 digest, swaps the installation atomically, and relaunches. Package-manager, Flatpak, or Snap installs open the release page instead of overwriting files managed externally.

Highlights

  • Real TDLib core, multi-account ready: Dedicated background receive isolate over libtdjson, instant account switching, passkey and QR sign-in, SOCKS5 / HTTP / MTProto / Web proxies, and encrypted session backup/import.
  • Rich messaging & composer: Replies, quotes, reactions, custom emoji, animated .tgs and .webm stickers, sticker studio, GIFs, polls, checklists, scheduled sends, rich-text formatting, LaTeX math, and inline/reply bots.
  • Media, voice & calls: Streaming fullscreen video player with Picture-in-Picture and desktop pop-out windows, voice and circular video notes, built-in music player with system Now Playing controls, and 1-to-1 / group voice calls.
  • Communities, topics & feeds: Chat folders, forum topic strips, Telegram Communities, story and channel photo/video feeds, Telegram Mini Apps, and optional on-device or user-configured AI translation and unread summaries.
  • Intentional design system: Explicit typography, spacing, corner-radius, and light/dark palette tokens (lib/theme/app_theme.dart), custom modal dialogs and controls, and project-owned vector icons (AppIcon / HeroAppIcons) rather than stock Material or Cupertino icon sets.
  • Localized in 8 languages: English, Simplified Chinese, Traditional Chinese, Japanese, Korean, German, French, and Spanish.

Why “Mithka”?

The name is a small piece of wordplay inspired by the penguin mascot and two tiny units of mass:

  • The mascot suggests a pengram: 🐧 + gram. Read as penta-gram, that is roughly 5 g.
  • One mithqāl (مثقال), a traditional unit of mass, is 4.6875 g.

Derived from mithqāl, Mithka is the featherweight sitting just lighter than the 5-gram penguin on an imaginary balance scale.


Architecture & Project Layout

mithka/
├── lib/
│   ├── app/              # App shell, split-pane layout, deep links, desktop windows
│   ├── auth/             # Login flow, multi-account store, QR & passkey sign-in
│   ├── bot_api/          # Bot API account mode & local TD-compatible adapter
│   ├── call/             # 1-to-1 and group call UI & native VoIP bridges
│   ├── channels/         # Forum/topic navigation and channel topic views
│   ├── chat/             # Conversation core (ChatView, ChatViewModel, session cache)
│   │   ├── admin/        # Chat info, members, permissions, and moderation logs
│   │   ├── ai_translation/ # Optional message translation & unread chat summaries
│   │   ├── appearance/   # Chat themes, wallpapers, and bubble previews
│   │   ├── composer/     # Input bar, voice/video capture, polls, rich composer
│   │   ├── links_search/ # t.me/tg:// router, link previews, internal browser, search
│   │   ├── media/        # Video player, stream server, music player, image editor
│   │   ├── messages/     # Message bubbles, albums, reactions, replies, action menus
│   │   ├── mini_apps/    # Telegram Mini Apps, bot platform, and invoice checkout
│   │   └── stickers/     # Stickers, custom emoji, GIFs, and sticker set studio
│   ├── chats/            # Chat list, folders, archive, and global search
│   ├── communities/      # Telegram Communities hierarchy and management
│   ├── components/       # Project-owned UI primitives, dialogs, and AppIcon set
│   ├── config/           # Build flags and git-ignored API credentials
│   ├── contacts/         # Contacts, groups/channels/bots directory, and add-people
│   ├── l10n/             # Generated localization keys and runtime loader
│   ├── media/            # Asset picker, camera capture, and media metadata probes
│   ├── moments/          # Stories viewer, story authoring, and channel Moments feed
│   ├── notifications/    # Local/push notifications and per-scope mute settings
│   ├── platform/         # Native method-channel bridges across mobile & desktop
│   ├── profile/          # User/chat profiles, QR cards, and collectible gifts
│   ├── security/         # Biometric/passcode lock and auto-clearing clipboard
│   ├── settings/         # Appearance, privacy, storage, proxy, AI, and blocking
│   ├── tdlib/            # Dart FFI bindings, background receive isolate, models
│   ├── theme/            # Design tokens, light/dark palettes, and cloud themes
│   └── update/           # GitHub release feed and Windows/Linux self-updater
├── apple/                # Shared Swift bridges compiled into both iOS and macOS
├── android/ ios/ macos/  # Platform runners and native plugins
├── linux/ windows/ ohos/ # Desktop and HarmonyOS Next runners
├── translations/         # Source XML string catalogues (8 locales) & check tools
├── scripts/              # Manifest-pinned tdjson installers & release automation
└── test/                 # Domain-organized unit, widget, and release-script suites

State is managed with provider and scoped ChangeNotifier view models. Native TDLib calls never block the UI isolate: lib/tdlib/td_client.dart runs the blocking td_receive loop on a dedicated background isolate, correlates @extra request/response pairs, and broadcasts typed updates per account slot.


Build from Source

Prerequisites

  • Flutter SDK (see .github/workflows/quality.yml for the pinned stable version)
  • Platform toolchain for your target OS (Xcode for iOS/macOS, Android SDK, Visual Studio C++ workload for Windows, or GTK3 development headers for Linux)
  • Python 3 (used by the manifest-pinned tdjson installer and verification tools)

1. Configure Telegram API credentials

Obtain your own api_id and api_hash from https://my.telegram.org, copy the example file, and fill in your credentials (lib/config/secrets.dart is git-ignored):

cp lib/config/secrets_example.dart lib/config/secrets.dart
class Secrets {
  static const int apiId = 123456;
  static const String apiHash = 'your_api_hash';
  static bool get isConfigured => apiId != 0 && apiHash.isNotEmpty;
}

(Tip: if you leave secrets_example.dart unchanged, the app still compiles and launches into a credential setup screen—useful for pure UI work and running widget tests.)

2. Install the prebuilt TDLib (tdjson) binary

Mithka does not require compiling TDLib locally. scripts/tdjson-manifest.json pins prebuilt, SHA-256-verified binaries published in iebb/mithka-tdjson:

# Android (installs under android/app/src/main/jniLibs/<abi>/)
./scripts/build-tdjson-android.sh arm64-v8a

# iOS (installs ios/tdjson/tdjson.xcframework, then install pods)
./scripts/build-tdjson-ios.sh
(cd ios && pod install)

# Desktop (macos, linux, or windows; optional arch: x64 or arm64)
./scripts/build-tdjson-desktop.sh macos native-libs/libtdjson.dylib
./scripts/build-tdjson-desktop.sh linux native-libs/libtdjson.so x64
./scripts/build-tdjson-desktop.sh windows native-libs/tdjson.dll x64

See NATIVE.md for bundle placement details and disk cleanup tips.

3. Install dependencies and run

flutter pub get
flutter run

Optional local configuration

  • Firebase Analytics: Optional for local builds. When android/app/google-services.json or ios/Runner/GoogleService-Info.plist is absent, Mithka builds and runs normally with analytics disabled.
  • Android release signing: Uses android/key.properties and its keystore if present, falling back to debug signing for local builds.
  • Compile-time Terms boundary: Official builds, nightlies, TestFlight, and store releases always compile with allowTelegramTosViolations = false (lib/config/build_flags.dart). Any contributor code covered by Telegram API Terms section 1.4 is completely inert unless explicitly self-built with --dart-define=I_DONT_FUCKING_CARE_ABOUT_TOS=true (which does not make such behavior compliant with Telegram’s terms).

Development & Verification

Before opening a pull request, run the local checks matching CI (quality.yml):

# Format & static analysis
dart format --output=none --set-exit-if-changed lib test integration_test test_driver
flutter analyze

# Localization & asset checks
python3 translations/tools/check.py
python3 translations/tools/gen_assets.py --check
python3 tool/check_l10n_strings.py
python3 tool/optimize_app_artwork.py --check

# Unit & widget test suite
flutter test --concurrency=4

Design token conventions live in DESIGN.md, localization workflows in docs/localization.md, test organization in test/README.md, and repository/PR rules in AGENTS.md.


Versioning, CI & Releases

  • master holds the next minor (X.Y.0): Validated on every push and PR by Quality and platform build workflows without publishing store artifacts directly.
  • Daily nightly builds (sync-nightly.yml, 00:00 UTC / 09:00 Tokyo): When master has new commits, GitHub Actions merges master into nightly, increments the patch version once (X.Y.1, X.Y.2, …; or ships X.Y.0 on the first sync of a new minor), and dispatches multi-platform GitHub prereleases, Google Play Open testing, and iOS/macOS TestFlight uploads. Patch numbers are never rewritten back to .0.
  • Twice-monthly store releases (weekly-store-release.yml, 1st & 15th at 09:00 Tokyo): Tags an immutable store-vX.Y.Z release above every patch used on that minor, submits that exact version to the App Store (iOS and macOS), Google Play, and GitHub Releases, then hands the HarmonyOS hap to Huawei AppGallery (appgallery-submit.yml). It then advances master to X.(Y+1).0 and immediately dispatches sync-nightly.yml so beta testers receive X.(Y+1).0 the same day.

License & Credits

Mithka is licensed under the BSD 3-Clause License.

TDLib and components under third_party/ remain governed by their respective licenses. Mithka does not distribute proprietary assets or trademarks from third-party applications.

Star History

Star History Chart

About

A Telegram client, but déjà vu

Resources

Stars

703 stars

Watchers

2 watching

Forks

Releases

Packages

Contributors

Languages