# Komai: Native Matrix Desktop Chat App

![Komai logo](https://etke.cc/img/komai/komai.svg)

At [etke.cc](https://etke.cc/), we host [Matrix](https://matrix.org/) servers for a living. Almost a decade ago, we were dissatisfied with Matrix self-hosting and launched the [matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy/) Ansible playbook (which our etke.cc SaaS is based on). Thanks to that, over time **we believe we solved Matrix self-hosting for thousands of users**.

All that time, we’ve also been spending a lot of hours staring at Matrix clients — and at things we wished were different.

Today we’re introducing [**Komai**](https://github.com/etkecc/komai) — a desktop-first, native Matrix chat app we’ve been building to scratch that itch. We can’t be sure we’ll solve Matrix on the desktop, but it’s a humble attempt at it.

![Komai main view](https://etke.cc/img/komai/main-view.webp)

Komai’s main view — communities sidebar, room list, and timeline side by side.

## 🤔 Why another Matrix client?

We just weren’t happy with what was out there.

Not a swipe at anyone — building a Matrix client is *genuinely hard*. The protocol surface is enormous (rooms, spaces, threads, receipts, presence, push rules, homeserver quirks…). End-to-end encryption is its own implementation and UX pain on top: multi-device, key backup, verification, cross-signing, recovery.

Stack all of that into one app and UX problems are inevitable. It’s more papercuts than anyone can bear.

Komai is an attempt to **make things a little better**.

## 🐱 Why we started with nheko

We didn’t want to write a Matrix client from scratch, even with the proliferation of brand-new Matrix clients in 2026.

We started with [nheko](https://nheko.im/nheko-reborn/nheko) — a native Qt/QML Matrix client. A solid foundation: native performance ([QML](https://en.wikipedia.org/wiki/QML) has its quirks, but still), mostly sensible defaults, a focused codebase (though with plenty of legacy code in it). And most importantly, not [Electron](https://www.electronjs.org/).

The original plan was modest: avoid doing too much. Apply some UX patches on top of upstream, send some back, ship a slightly nicer build of nheko.

That plan continued for **about 100 patches** and we still craved more. So much for “avoid doing too much”.

## 🤝 Why not just contribute to nheko?

Short answer: too many ideas, too little patience for a slow process.

We wanted to be able to change things in major and sometimes controversial ways. We wanted to be the masters of our own destiny.

We did contribute upstream where it made sense. For example, to [mtxclient](https://github.com/Nheko-Reborn/mtxclient) (the Matrix client library nheko was using):

- [a fix for a double-base64-encoding bug in online key backup](https://github.com/Nheko-Reborn/mtxclient/pull/113)
- [adding an optional `filename` field on image, audio, and video messages](https://github.com/Nheko-Reborn/mtxclient/pull/114)

All of which is moot now anyway — soon after, we stopped using `mtxclient`. More on that in a moment.

## 🚢 The Ship of Theseus moment

After ~100 patches, tracking upstream while carrying that pile started to outweigh the benefit.

Replace enough planks and you’re sailing a [different ship](https://en.wikipedia.org/wiki/Ship_of_Theseus). We had a choice: keep reconciling diverging goals, or stop pretending and ship a client of our own.

**We chose independence and picked up a chainsaw**.

## 🔧 Tearing out the encryption core

The most consequential change wasn’t a UX patch. It was an engine swap.

Nheko’s Matrix layer was built on [mtxclient](https://github.com/Nheko-Reborn/mtxclient), [libolm](https://gitlab.matrix.org/matrix-org/olm) and [LMDB](https://en.wikipedia.org/wiki/Lightning_Memory-Mapped_Database), all deeply intertwined.

These Matrix libraries are behind where the Matrix ecosystem is heading. [libolm has been deprecated](https://matrix.org/blog/2024/08/libolm-deprecation/) for a while, and there’s a long-standing nheko issue discussing a possible move to [matrix-rust-sdk](https://github.com/matrix-org/matrix-rust-sdk) ([Nheko-Reborn/nheko#1786](https://github.com/Nheko-Reborn/nheko/issues/1786)). nheko maintainers are right to hesitate: it’s a *huge* amount of work for a small team, and the existing crypto stack is wired deep into the codebase.

Two things made it tractable for us anyway:

- AI-assisted development carrying us through. More on this below.
- Trusting `matrix-rust-sdk` to be mature enough and worth the move — better encryption (vodozemac), sliding sync, modern MSC support, and active development.

So **over a few days of work, [Codex](https://openai.com/index/introducing-codex/) ripped out [mtxclient](https://github.com/Nheko-Reborn/mtxclient) and [libolm](https://gitlab.matrix.org/matrix-org/olm) and dropped in [matrix-rust-sdk](https://github.com/matrix-org/matrix-rust-sdk)**.

**We’re surprised the switch worked as well as it did**. Nevertheless, it still hurt. The change brought **a wave of regressions we spent a long time climbing back out of** and **delayed our launch by weeks**.

The good news: Komai now sits on the same Rust runtime the wider Matrix ecosystem is converging on.

## 🦀 Rust, and more Rust

The matrix-rust-sdk transplant wasn’t a one-off — it set Komai’s direction: **more Rust, less legacy C++**, especially for anything protocol- or text-shaped.

Other pieces have quietly moved across the line too: URL detection in messages ([linkify](https://crates.io/crates/linkify)), [BlurHash](https://blurha.sh/) encoding and decoding ([blurhash](https://crates.io/crates/blurhash)), code-block syntax highlighting ([syntect](https://crates.io/crates/syntect)), YAML parsing for settings and themes, and Matrix server discovery via [Continuwuity](https://continuwuity.org/)’s [resolvematrix](https://forgejo.ellis.link/continuwuation/resolvematrix) crate (vendored and patched up).

Each move chips away at the C++ surface we maintain and gives us cleaner, better-tested foundations in return.

## 📦 And then we kept adding features

Once the lights came back on after the matrix-rust-sdk migration, we kept iterating.

A few things we’re opinionated about — Komai’s quiet design philosophy:

- 🖥️ **Desktop-first UX** — optimized for large screens, not a stretched phone UI
- 👓 **Readable and easy to use** — comfortable text sizes, large hit targets (see [Fitts’s law](https://www.nngroup.com/articles/fitts-law/)), great color contrast
- 🎨 **Yours to shape** — [themeable](https://github.com/etkecc/komai/blob/main/docs/user-guide/features/themes.md) and [config-management-friendly](https://github.com/etkecc/komai/blob/main/docs/user-guide/settings/README.md#configuration-management) via plain-YAML files
- ⚡ **Native performance** as a design constraint, not an afterthought
- 🎓 **Educate, don’t over-abstract** — like [Arch Linux](https://wiki.archlinux.org/title/Arch_Linux), expose Matrix’s real concepts rather than paper over them
- 🧠 **For both grandma and power users** — neither dumbed down nor buried in complexity

A few of the things that came out of that:

- 📑 [**Browser-style room tabs**](https://github.com/etkecc/komai/blob/main/docs/user-guide/features/tabs.md) — open multiple conversations side by side, pin the ones you keep coming back to. A power-user feature still rare among Matrix clients; the idea was sparked by a presentation from the [Robrix](https://github.com/project-robius/robrix/) team.
  
  ![Komai room tabs](https://etke.cc/img/komai/tabs.webp)
  
  2 rooms open as tabs. All can be reordered, closed, and reopened and auto-restore on restart.
- 🌐 **A curated registration page** — instead of funneling new users to the [matrix.org](https://matrix.org/) homeserver by default, the Register page features a [curated set](https://github.com/etkecc/komai/blob/main/resources/serverlist/servers.yml) of public servers (seeded from [servers.joinmatrix.org](https://servers.joinmatrix.org/)). **Decentralization should start at sign-up**. We’re glad to see [FluffyChat](https://github.com/krille-chan/fluffychat) recently moved in a similar direction, though [more conservatively](https://github.com/krille-chan/fluffychat/blob/6dcb5cc8e141b1690c51acdf4cabc1d8ca7a92e3/recommended_homeservers.json).
  
  ![Komai registration page](https://etke.cc/img/komai/registration.webp)
  
  The Register page surfaces a curated set of public servers — not just matrix.org.
- 🧭 [**A polished room directory**](https://github.com/etkecc/komai/blob/main/docs/user-guide/features/room-directory.md) with first-class [Matrix Rooms Search](https://github.com/etkecc/mrs) support (enabled by default via [matrixrooms.info](https://matrixrooms.info/)), language and room-size filters.
  
  ![Komai room directory](https://etke.cc/img/komai/room-directory-matrix-rooms-search.webp)
  
  The room directory, backed by Matrix Rooms Search — with language and room-size filters.
- 🎨 [**10+ built-in themes**](https://github.com/etkecc/komai/blob/main/docs/user-guide/features/themes.md), all maintained to meet [WCAG AA contrast](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) — Dark Matrix, Catppuccin, Dracula, Nord, Tokyo Night, Rose Pine, and more. [🗂️ User themes](https://github.com/etkecc/komai/blob/main/docs/user-guide/features/themes.md#-user-themes) are also supported.
  
  ![Komai Dark Matrix theme](https://etke.cc/img/komai/themes-dark-matrix.webp)
  
  The Dark Matrix theme — one of 10+ built-in WCAG AA-contrast themes.
- 🎙️ [**Voice transcription**](https://github.com/etkecc/komai/blob/main/docs/user-guide/features/voice-transcription.md) — long-press `Space` to dictate into the composer (an interaction pattern inspired by [Claude](https://claude.ai/)). A more respectful (and skimmable, searchable) way to send a message by voice than dropping a voice clip on someone (which Komai also supports). Works with [OpenAI](https://openai.com/) cloud or any OpenAI-compatible local server.
- 🤖 [**Automation hooks**](https://github.com/etkecc/komai/blob/main/docs/user-guide/features/automations/README.md) — drive Komai from [CLI](https://github.com/etkecc/komai/blob/main/docs/user-guide/features/automations/cli.md), [D-Bus](https://github.com/etkecc/komai/blob/main/docs/user-guide/features/automations/dbus.md), or an AI agent over the [Model Context Protocol](https://github.com/etkecc/komai/blob/main/docs/user-guide/features/automations/mcp.md).
- 👥 [**Multi-account**](https://github.com/etkecc/komai/blob/main/docs/user-guide/features/application-profiles.md) via dedicated application profiles — fully separate identities and state, in one application (each profile in its own window).
- 🌐 [**30+ fully translated languages**](https://github.com/etkecc/komai/blob/main/docs/maintainers/translations.md) — inherited nheko translations, plus AI-assisted gap filling across the board.

To learn more, see the [✨ features overview](https://github.com/etkecc/komai/blob/main/docs/user-guide/features/README.md).

## 🤖 Built openly with AI

Komai is heavily [🤖 AI-assisted](https://github.com/etkecc/komai/blob/main/docs/user-guide/ai.md), and we don’t hide it.

C++/QML/Rust isn’t [our team](https://etke.cc/about/)’s strong suit, so professional engineers and AI coding agents ([Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), [Codex](https://openai.com/index/introducing-codex/)) are working together to hopefully build a Matrix app you can love.

Our bet: **AI in capable hands can deliver above-average results.**

## 📍 Where Komai is today

Komai is **good enough to ship and gather some feedback**. Not finished, not flawless, but:

- a daily-driver Matrix client we use ourselves
- on a modern, actively-developed Matrix stack ([matrix-rust-sdk](https://github.com/matrix-org/matrix-rust-sdk))
- with [a feature set](https://github.com/etkecc/komai/blob/main/docs/user-guide/features/README.md) that holds its own against any other native Matrix client
- fully [Free Software](https://www.gnu.org/philosophy/free-sw.html) (GPL-3.0-or-later), no CLA, no contributor gatekeeping

Some features are still missing, others still unpolished. Try it. We’ll keep iterating from there.

## 📥 Try it

Komai is **Linux-only** (x86\_64) for now, though [building on Windows or Mac may be possible](https://github.com/etkecc/komai/blob/main/docs/maintainers/packaging/native.md#-windows-and-macos-untested) (still untested).

It ships as AppImage, Flatpak, and Snap on [GitHub Releases](https://github.com/etkecc/komai/releases), and as a [komai](https://aur.archlinux.org/packages/komai) package on the Arch Linux [AUR](https://aur.archlinux.org/).

See the [📥 Installation guide](https://github.com/etkecc/komai/blob/main/docs/user-guide/installation.md) for details.

## 💬 Get involved

- 💬 Matrix room: [#komai:etke.cc](https://matrix.to/#/%23komai:etke.cc)
- 🐙 GitHub: [etkecc/komai](https://github.com/etkecc/komai)

## 🙏 Thanks

Komai owes a lot to [nheko](https://nheko.im/nheko-reborn/nheko) (the codebase ancestry) and to the [matrix-rust-sdk](https://github.com/matrix-org/matrix-rust-sdk) team (the encryption core we now ride on) — among many others; the full list lives in the [Acknowledgements](https://github.com/etkecc/komai#-acknowledgements) section of the Komai README.


---
* [llms.txt](https://etke.cc/llms.txt): full site index in markdown