weechat-android: an IRC relay client that needs a WeeChat server

A relay client, not an IRC client

This is a WeeChat relay client for Android, and the distinction is stated immediately: this application is not a standalone an IRC client. It connects to WeeChat that has to be running on a remote machine, and if you are looking for a standalone IRC client for Android you will need to look elsewhere.

That framing explains the whole feature set. What the app gives you is not IRC protocol handling but the experience of a WeeChat user on a phone, because WeeChat itself provides the buffer model, the plugin system, the command completion, the per-buffer formatting and the network connections, and the app is a window onto that.

The practical implication for anyone setting it up is that there are two halves. A WeeChat instance runs on a server you control, with the relay enabled, and the app connects to it. The project's own quickstart guide and FAQ are the setup documentation, and the README points at both.

The app is distributed through F-Droid and Google Play, and the two listings are different builds. The Google Play link points at a package with a `.dev` suffix, `com.ubergeek42.WeechatAndroid.dev`, while the F-Droid listing is `com.ubergeek42.WeechatAndroid`, so the development channel and the distributed channel are separate artifacts rather than one build.

The README also points to a `weechat-relay-example/` directory in the repository, which is the practical starting point for understanding what the app expects to connect to.

The language is Kotlin, though the project was not always Kotlin: the v1.3 changelog notes that parts of the app are using Kotlin now, so the migration was gradual. The last push was on 2026-10-18, the project is not archived, and the licence file in the repository root is `LICENSE-2.0.txt`.

TLS work took five releases to settle

The most instructive thing in the repository is the changelog, because it shows how much of this client is about not trusting the network.

Version 1.1 is where the security work starts. It added a new certificate dialog that displays the full certificate chain, implemented SSL certificate pinning, added support for client SSL certificates, and added support for Ed25519 keys thanks to sshlib. It also notes that where possible, RSA, EC and DSA keys are stored inside security hardware, which is the Android keystore doing the right thing with your private key.

Version 1.2 added the ability for users to interactively accept or reject SSH host keys, and private SSH keys in PKCS #8 format. Version 1.3 followed with the ability to upload files via user-supplied HTTP POST services.

Then the fixes arrive. Version 1.8.1 fixed an issue with Ed25519 keys during upgrade, and updated the Android Gradle Plugin to fix the build on F-Droid. Version 1.8 fixed not being able to connect to servers that require SNI, fixed cleartext web traffic not going through, and fixed the wrong message shown in case of a TLS error. Version 1.8.1 also reworked the ping logic to comply with Google Play requirements, which is the kind of change that says a lot about what running a long-lived relay connection on a phone involves.

Version 1.9 fixed strange behavior resulting from handling WeeChat pointers as signed numbers, and fixed the importing of PKCS #8 Ed25519 keys.

Reading that sequence together, the picture is of a client that takes the security of a persistent connection to a server you own seriously, and that has spent several releases learning the hard way how many ways a TLS connection can go wrong on a mobile network. The user-facing consequence is that certificate handling has its own dialog with a full chain, host keys have a prompt, and pinning is available, which is a feature set you would not expect from a chat client and which you would want if the server is yours and the connection is long-lived.

What the app does with buffers

The feature list across the changelog is mostly about how the client presents WeeChat's own concepts on a small screen, and a few entries are about the parts that are specifically mobile.

Version 1.6 is the substantial one. It added search functionality, a floating go to bottom button, and a connectivity indicator. It also changed the copy dialog so it can select text and copy several messages at once, stopped the interface from being locked up while disconnected, stopped chat lines from being thrown away when not synchronizing, made the chat scroll position remembered on rotation, and started drawing the app behind the system bars on supported devices, with new chat line change animations. It also stopped the local tab completer from being used when completing command-like text, which is the sensible behaviour when the command is being typed for a remote shell rather than for a local one.

Version 1.10 added an option to not move hot buffers to the top of the buffer list, and handled the relay events `_buffer_cleared` and `_buffer_line_data_changed`. The first of those is the interesting one, because it means the app tracks the relay event stream rather than only polling for state.

The relay events matter more than they look. The changelog for version 0.14 mentions reworking a major part of the networking code and using a different WebSocket library, nv-websocket-client, and the relay protocol is event driven, so the app is subscribing to buffer changes and being told about them rather than refetching everything.

Mobile-specific behaviour accumulates over the versions. Version 1.7 added launcher and direct share shortcuts, and support for Bubbles on Android 11, and removed the storage access permission on Android 9 and above. Version 1.9 added drag and drop files on buffers to share, and made the volume keys navigate input history.

Version 1.11, the latest, is mostly about error reporting: use snackbars for error messages, include the full traceback with errors when available, and show more extensive error details when file upload fails. It also added support for themed app icons, targeted Android API 35, and dropped support for Android API below 26. That last change is the one to note, since it narrows the devices the current release runs on.

How the project is built and where its pieces live

The repository layout is the standard Gradle Android project, with a few directories that are worth naming.

There is an `app/` directory for the Android application, built with `build.gradle.kts` and the Kotlin DSL, alongside `settings.gradle.kts`, `gradle.properties`, `gradle/` and the `gradlew` wrapper scripts. The `metadata/` directory holds the store listing material, with `en-US` translations and the phone screenshots the README embeds, and `crowdin.yml` is the translation service configuration, which explains the German translation added in version 1.0 and how the other locales are handled.

The `relay/` directory is the part that matters technically. It is where the relay protocol implementation lives, which is the part of the client that actually talks to WeeChat.

Then there are two directories that show how the project treats its own history. `releases/` holds the packaged release artefacts, and `weechat-relay-example/` is the example relay implementation the app is developed against.

Two smaller entries are worth a mention. There is a `cats/` directory, which is not a typo, and a `build.gradle.kts` at the root alongside the one in `app/`, which in a multi-module Gradle build usually means the root script holds the shared configuration.

The build documentation lives in the wiki rather than the repository, with a Getting started with the code guide that also covers building from the command line. The README asks contributors to check with the project on IRC before starting a substantial rewrite, and puts the channel at #weechat-android on irc.libera.chat, which is the convention for this kind of project.

For bug reports, the README asks you to include the build ID, which you can find in Settings then About, and which looks something like v0.13-123-g1234567. That is a useful detail, because it identifies the exact commit rather than the release, and several of the changelog entries are fixes for behaviour that depends on a particular WeeChat version rather than on the app.

What the relay protocol changes about the connection model

The app does not speak IRC, and the relay protocol is what makes the whole thing possible, so it is worth saying what that protocol actually is.

WeeChat runs on your server and keeps the connection to the IRC networks. The relay protocol is the channel through which a second program, in this case the app, asks WeeChat to do things and tells it what the user typed. The app is therefore a remote control for a running WeeChat instance, and the buffers it displays are WeeChat's buffers, not the app's own.

That has two consequences that show up in daily use. The first is that the state lives on the server. Your buffer history, your plugins, your hotkeys configuration and the network connections all persist in the WeeChat instance, so opening the app on a new phone shows the same history rather than an empty screen, and it is the WeeChat configuration that decides what appears.

The second is that the connection is long-lived and it matters. The changelog entries about reworking the networking code and switching WebSocket libraries, about SNI-required servers, about cleartext web traffic and about reworking the ping logic to comply with Google Play requirements are all about keeping one connection alive across a mobile network that may drop it, may be behind a carrier proxy, and may be put to sleep by the operating system.

The event-driven part is the newer addition. Handling the relay events `_buffer_cleared` and `_buffer_line_data_changed` in version 1.10 means the app is told when something changes rather than only asking for the current state, so a message arriving while you are reading scrolls the app to the bottom automatically and the go to bottom button appears. The floating button in version 1.6 and the connectivity indicator are the visible parts of that design.

The practical takeaway for someone setting this up is that the server side matters as much as the app. The WeeChat instance has to be running with the relay enabled and reachable, and the relay configuration is what determines whether the connection is encrypted and who may connect. The app's certificate pinning and client certificate support only help if the server is configured to present a certificate the app will accept, which is a two-sided setup.

The other side of the same point is that this app is not a way to reach IRC from a network that blocks it in some other way, since all the traffic is between your phone and your own server. If the server cannot reach the IRC network, neither can the app, and if the server can, the app does not need to.

Editorial conclusion

Adopt weechat-android if you already run WeeChat on a remote host and want the same buffers, plugins and completion on your phone, since the client speaks the relay protocol rather than talking to IRC servers itself. Do not adopt it as a standalone IRC client, because the README is explicit that it is not one, and check first that your WeeChat instance has the relay enabled and reachable, since the app connects to WeeChat and not to the networks WeeChat is connected to.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. ubergeek42/weechat-android on GitHub