Mithka: a Flutter and TDLib Telegram client you compile yourself

What Mithka solves, and for whom

Mithka is an independent, cross-platform Telegram client for Android, iOS, Windows, macOS, and Linux. The README is explicit that it is unofficial and not affiliated with, endorsed by, or connected to Telegram, and that it connects to Telegram through TDLib using API credentials the user provides. That sentence frames the whole project: this is a client for people who want to run their own Telegram front end, not a service that hides the plumbing.

The target reader is someone who finds the official clients visually uniform and wants an interface built from Cupertino and custom components rather than Material dialogs, snackbars, or switches. The README lists what that interface covers: live chat lists and conversations, reactions, stickers including animated .tgs and .webm, voice messages, polls, checklists, Telegram Communities, location sharing, contacts, profiles, moments-style stories, settings, and a one-to-one calling interface. That is a broad feature surface for a single-maintainer client, and it is the reason the project is interesting rather than merely cute.

The name is wordplay. The README derives it from mithqāl, a traditional Islamic unit of mass of roughly 4.6875 g, positioned just below the Telegram penguin on an imaginary scale. It tells you the maintainer treats this as a personal project with a point of view, not a product launch.

Flutter on top, TDLib underneath

The architecture is two layers. The Flutter interface lives in lib/ and uses provider with ChangeNotifier for state management. TDLib is connected through Dart FFI in lib/tdlib/. A pinned native libtdjson binary is installed per platform and is deliberately not committed to the repository.

That split has a practical consequence. The Dart side is ordinary Flutter code you can read and modify. The Telegram protocol work happens inside a prebuilt native library that the repository does not compile. The README states plainly that this repository does not build TDLib from source; instead, scripts/tdjson-manifest.json pins matching prebuilt Android, iOS, macOS, Linux, and Windows artifacts published by iebb/mithka-tdjson, and helper scripts download and verify them.

So the data flow is: your Flutter widgets call into lib/tdlib/, which crosses the FFI boundary into libtdjson, which speaks to Telegram using your api_id and api_hash. If you want to change how a chat list renders, you are in normal Flutter territory. If you want to change how a message is parsed off the wire, you are not, unless you fork the tdjson artifacts too. The README does not describe a supported path for patching TDLib itself, and NATIVE.md is the document it points to for exact paths and cleanup guidance.

Building Mithka from source: credentials, native library, first run

The README gives a three-step build. First, create your own api_id and api_hash at my.telegram.org and place them in the git-ignored lib/config/secrets.dart. The file it shows looks like this:

class Secrets {
  static const int apiId = 123456;
  static const String apiHash = 'your_api_hash';
  static bool get isConfigured => apiId != 0 && apiHash.isNotEmpty;
}

Second, install the native TDLib library. The helper scripts download and verify the pinned artifacts. For Android you install one or more ABIs under android/app/src/main/jniLibs/<abi>/:

scripts/build-tdjson-android.sh arm64-v8a

For iOS the script installs ios/tdjson/tdjson.xcframework for the Runner target:

scripts/build-tdjson-ios.sh

For desktop the script writes the library to a path you choose, and Linux and Windows additionally take an architecture, x64 by default or arm64:

scripts/build-tdjson-desktop.sh macos /tmp/libtdjson.dylib
scripts/build-tdjson-desktop.sh linux /tmp/libtdjson.so arm64

Third, fetch dependencies and run:

flutter pub get
flutter run # Run on a connected device or simulator

Firebase Analytics is optional for local development. The README states that if android/app/google-services.json or ios/Runner/GoogleService-Info.plist is missing, or contains only an empty placeholder, the app builds and runs with analytics disabled. Maintainers and release CI supply the real, git-ignored configuration files. Android release builds use the project upload key when android/key.properties and its referenced keystore exist; otherwise the build falls back to a debug signature. Neither file is committed.

The self-updater and where it refuses to act

Windows and Linux packages update themselves. The README points to Settings, About, Check for Updates, which downloads the release package for that architecture, verifies it against the SHA-256 that GitHub publishes, and swaps the install in place before relaunching. AppImages replace the original file while preserving its filename. Updates check the latest stable GitHub release, including when you are running a nightly build.

The interesting part is the boundary. The README says an install owned by a package manager, Flatpak, or Snap is pointed at the releases page instead of being replaced underneath its own updater. That is the right call, and it also means the convenience of in-place updates only exists for installs Mithka itself owns. If you install through a distribution channel, you are back to that channel's release cadence.

Linux packaging comes as x64 and arm64 AppImages alongside portable tarballs. You make the AppImage executable with chmod +x Mithka.AppImage and run it from a directory you can write to. CI verifies each AppImage launches on Ubuntu 24.04; the README states older distributions are not a supported baseline. Windows releases include per-architecture setup.exe installers and portable ZIPs, and the installer is per-user, needs no administrator access, creates Start Menu and optional desktop shortcuts, and registers Mithka in Installed Apps.

Nightly builds, release branches, and the cost of following master

The release channel is the strongest signal about what kind of project this is. The repository's recent releases are all nightlies: v1.4.8-nightly.20260916.339e8b5, v1.4.7-nightly.20260915.07566b8, v1.4.6-nightly.20260911.9fa1413. The last push to the repository was on 2026-09-17, and the newest nightly is dated 2026-09-16, so the cadence is close to daily.

The README describes the branch model. master is the validated development branch and does not publish packages to GitHub, Google Play, or TestFlight. Pushing a validated master commit to release-ios starts Xcode Cloud archives for iOS and macOS and delivers them to external TestFlight testers, and Xcode Cloud keeps the same major and minor version while setting the patch version to 0. The README text available here is truncated mid-sentence after that point, so the rest of the release pipeline is not documented in what I can verify.

For a user this means the stable installs on Google Play, the App Store, and GitHub releases move on their own schedule, while the prerelease channel moves constantly. The README also notes that the self-updater checks the latest stable GitHub release even when you run a nightly, so a nightly install will not chase nightlies forever. That is a sensible default, but it also means the nightly you installed is not the nightly you will keep.

Where Mithka is the wrong choice

The first limitation is the one the README states in its own warning block: Mithka connects to Telegram using Telegram API credentials that you provide, and you use it at your own risk and in accordance with Telegram's Terms of Service and API Terms. If you are not willing to register an application at my.telegram.org and hold that credential, the source build is closed to you. The published store builds presumably carry the maintainer's credentials, but the README does not say so, and I will not guess.

The second is the native library boundary. The repository does not build TDLib from source; it downloads prebuilt artifacts pinned in scripts/tdjson-manifest.json from iebb/mithka-tdjson. If a Telegram protocol change lands and the pinned artifacts are not refreshed, the Dart side cannot compensate. You are dependent on a second repository's release schedule, and the README does not describe a fallback.

The third is platform baseline. Linux CI verifies AppImages on Ubuntu 24.04 and the README explicitly says older distributions are not a supported baseline. If you run an older LTS, you are outside what the project tests.

The fourth is that this is an unofficial client holding your Telegram session. The README's disclaimers about Telegram and about Tencent and QQ are careful and specific, which is a good sign, but they are disclaimers, not a security review. Nothing in the README describes an audit, a threat model, or a session-storage design. If your threat model requires those documents, they are not here.

How Mithka differs from the official Telegram desktop client

The obvious alternative is Telegram's own client. The difference is not features, since the README's list of what Mithka offers maps closely to what any Telegram client offers. The difference is the rendering stack and who owns the build.

Telegram Desktop is a native C++ application. Mithka is a Flutter application that talks to TDLib over Dart FFI, and its README states that the interface uses Cupertino and custom components rather than Material dialogs, snackbars, or switches. That is a deliberate visual choice, not a technical requirement, and it is the reason someone would pick Mithka over the official client: they want a specific look on desktop and mobile from the same codebase, and they are willing to build it.

The second difference is update ownership. The official client updates through its own channel. Mithka updates itself only when Mithka owns the install; package manager, Flatpak, and Snap installs are redirected to the releases page. If you want a client that a distribution maintains for you, the official packages are the more predictable path, and Mithka's own README effectively concedes that by handing those installs back to their updater.

The third difference is the credential. With the official client you log in. With a Mithka source build you register an application and compile its credentials in. That is a real amount of friction, and it is the single clearest filter on who this project is for.

Licence and what the BSD-3-Clause grant does not cover

The repository is licensed BSD-3-Clause. That is a permissive licence: it allows use, modification, and redistribution with the copyright notice and disclaimer retained, and it does not impose a copyleft obligation on your changes. If you fork Mithka and ship a modified client, the licence does not require you to publish your source.

What the licence does not do is grant you anything beyond the code in this repository. The README is careful about this. Telegram is a trademark of its respective owner, and Mithka is not affiliated with, endorsed by, or connected to Telegram. The README also states that Mithka is not affiliated with, endorsed by, sponsored by, or otherwise connected to Tencent or QQ, and that it does not use, include, copy, or redistribute proprietary QQ assets. The name and the penguin wordplay are clearly a nod in that direction, and the project draws the legal line explicitly rather than leaving it implicit.

The native libtdjson binaries are a separate matter. They are not committed here; they are downloaded from iebb/mithka-tdjson under whatever terms that repository carries. The README does not state those terms, so if you plan to redistribute a built Mithka binary, check that repository's licence before you do. This is a description of what the files say, not legal advice.

Editorial conclusion

Adopt Mithka if you want a Telegram client whose interface is deliberately not Material, you are comfortable supplying your own api_id and api_hash, and you accept nightly builds as the normal desktop channel. Do not adopt it if you need a supported enterprise client, you rely on a package manager to own your install, or you expect the repository to build TDLib from source. Before committing, verify three things: that scripts/tdjson-manifest.json pins an artifact for your platform and architecture, that a build without google-services.json or GoogleService-Info.plist runs with analytics disabled, and that Settings, About, Check for Updates behaves as the README describes on your install type.

Frequently asked questions

Official sources

1. iebb/mithka on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases