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.
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.
| 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.
- macOS: The Mac App Store build is the recommended install; it updates
through the App Store. The GitHub release also ships per-architecture
.ziparchives. 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.exeinstallers (no administrator rights required; registers Start Menu shortcuts and Installed Apps) and portable ZIP archives forx64andarm64. - Linux ships
x64andarm64AppImages alongside portable tarballs, validated in CI against Ubuntu 24.04 (chmod +x Mithka.AppImageand 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.
- 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
.tgsand.webmstickers, 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.
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.
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.
- Flutter SDK (see
.github/workflows/quality.ymlfor 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
tdjsoninstaller and verification tools)
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.dartclass 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.)
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 x64See NATIVE.md for bundle placement details and disk cleanup tips.
flutter pub get
flutter run- Firebase Analytics: Optional for local builds. When
android/app/google-services.jsonorios/Runner/GoogleService-Info.plistis absent, Mithka builds and runs normally with analytics disabled. - Android release signing: Uses
android/key.propertiesand 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).
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=4Design 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.
masterholds the next minor (X.Y.0): Validated on every push and PR byQualityand platform build workflows without publishing store artifacts directly.- Daily nightly builds (
sync-nightly.yml, 00:00 UTC / 09:00 Tokyo): Whenmasterhas new commits, GitHub Actions mergesmasterintonightly, increments the patch version once (X.Y.1,X.Y.2, …; or shipsX.Y.0on 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 immutablestore-vX.Y.Zrelease 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 advancesmastertoX.(Y+1).0and immediately dispatchessync-nightly.ymlso beta testers receiveX.(Y+1).0the same day.
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.

