ThunderWren 🐦⚡

A Wear OS companion for Thunderbird for Android.

ThunderWren brings your Thunderbird inbox to smartwatches running Wear OS 3+. Thunderbird on your phone keeps doing the mail syncing. The watch shows your inboxes, lets you triage messages with a tap or a swipe, and sends quick replies through the phone. For anything longer it hands off to the phone. The watch never stores your passwords or connects to a mail server.

It lives in a fork of the Thunderbird for Android repository. The design is proposed upstream in RFC 0010.

Important

Project status: beta (0.1.0-beta5). The phone and watch sides are implemented, covered by unit and UI tests, and tested on a Pixel 10 Pro Fold with a Pixel Watch 5, as well as on emulators. The watch needs the Thunderbird phone app built from this fork; the Thunderbird app from the Play Store doesn't include the companion.

Built with AI. Most of this code was written with an AI coding assistant (Claude Code), directed and tested by the fork's maintainer. It follows the repository's AGENTS.md rules for AI-assisted contributions.

Just curious? You don't need a phone. Install only the watch app and tap Try the demo.

The demo mailbox, rendered from the real watch UI.

---

✅ What works today

Area	Status	Notes
Inbox on the watch	✅	The newest 25 messages with sender, subject, preview, date, and unread/starred state.
All inboxes, Unread, Starred, or one account	✅	Tap the mailbox name at the top of the inbox to switch. "Unread" and "Starred" filter all inboxes. The watch remembers your choice.
Account monograms	✅	In mixed views, each message shows its account's monogram and color, as in Thunderbird.
Swipe to archive or delete	✅	Swipe a message to the left: a full swipe archives it, and Delete is next to Archive. In the watch settings, choose delete as the full swipe, or swipe left for one and right for the other. Screen readers get the same actions.
Watch settings	✅	Swipe actions, confirm before deleting, mark as read when opened, and message previews. Open them from the end of the inbox.
Mark read/unread, star, archive, delete	✅	Sent to the phone, which applies them like the phone app does. Opening a message marks it as read.
Mark all as read	✅	At the end of any mailbox, after a confirmation.
Reply from the watch	✅	Speak, type, or pick a ready-made reply, review it, and send. Thunderbird on the phone sends it from the right account, with your signature and quoting settings, and marks the message as answered. Encrypted messages are answered on the phone.
Read the whole message	✅	Opening a message loads its whole text from the phone. Very long messages, or ones the phone has only partly downloaded, say that the rest is on the phone.
Open on phone	✅	Opens the message in Thunderbird on the phone, for reading in full.
Tile	✅	Shows the unread count and the newest unread messages. Tap one to open it.
Complication	✅	Shows the unread count on your watch face.
Privacy	✅	The Tile and complication follow Thunderbird's Lock Screen Notifications setting (senders and subjects, senders only, count only, or nothing). The default is count only.
Encrypted messages	✅	Shown as encrypted, with a prompt to read them on the phone.
Works briefly offline	✅	The watch keeps the last data the phone sent.
Demo mailbox	✅	Try the demo on the watch shows a sample mailbox where everything above works, no phone needed. Real data from Thunderbird on the phone replaces it automatically.
Phone notifications on the watch	✅ Improved	Thunderbird's notifications offer Reply (voice, keyboard, or ready-made replies, sent by the phone) and Star on the watch, and their actions follow your notification action order.
Folders other than the inbox	⬜ Not started
Standalone mode (no phone)	⬜ Not planned yet	See the RFC for why the phone does the syncing.

---

🧱 How it works

Phone: Thunderbird (full/Play build)             Watch: ThunderWren
┌──────────────────────────────────┐             ┌──────────────────────────┐
│ :feature:wear:companion:internal │─ mailboxes ▶│ Inbox, mailbox picker,   │
│  • publishes each mailbox        │─ inboxes ──▶│ message and reply        │
│  • applies watch actions         │◀─ requests ─│ screens, Tile,           │
│  • sends replies                 │             │ complication             │
│  • "open on phone" entry point   │             │                          │
└──────────────────────────────────┘             └──────────────────────────┘
                both use :feature:wear:companion:api (protocol)

• :feature:wear:companion:api: the shared protocol, covering Data Layer paths, message and mailbox models, and the JSON codec.
• :feature:wear:companion:internal: the phone side, included in Thunderbird's full (Play) flavor. It publishes the mailbox list and one snapshot per mailbox over the Wearable Data Layer. It also applies actions through MessagingController, sends replies with QuickReplySender (in legacy:core, shared with the notification Reply action), and opens messages on request.
• :feature:wear:companion:noop: included in the foss (F-Droid) flavor instead, because the Data Layer needs Google Play Services.
• :app-thunderwren: the Wear OS app. It depends only on the protocol module.

---

🛠️ Getting Started

Requirements

• A recent Android Studio release that supports Android Gradle Plugin 9.4. If Gradle sync says the AGP version is unsupported, update Android Studio.
• Gradle JDK 17 or newer. Android Studio's bundled JDK works.
• Android SDK Platform 37 (the project's compileSdk). Android Studio offers to install it on first sync.
• A phone emulator with Google Play (or a real phone) and a Wear OS 3+ (API 30+) emulator, paired with each other.

Quickest try: the demo (watch only)

1. Create and start a Wear OS Small Round emulator (API 30 or newer) in Device Manager.
2. Select the app-thunderwren run configuration and run it on the watch.
3. Tap Try the demo. You get "All inboxes", "Unread", "Starred", and a Work and a Personal account with sample messages. Open, star, reply to, swipe away, and mark them as read, switch mailboxes, and add the Tile and complication. Nothing is sent anywhere.

Exit demo at the bottom of the inbox returns to the "Connect your phone" screen. If Thunderbird on a paired phone connects, its real inbox replaces the demo automatically.

Pair a phone and a watch emulator

1. In Device Manager, create a phone emulator using a system image with Google Play, and a Wear OS Small Round emulator (API 30 or newer).
2. Start both, then use Tools → Device Manager → ⋮ → Pair Wearable (Android Studio's pairing assistant) to pair them. It installs the Wear OS companion app on the phone.

Install both apps

The phone app and the watch app must have the same application ID and signing key, or the Data Layer won't connect them. Debug builds from the same computer satisfy both (net.thunderbird.android.debug, signed with your debug key).

1. Select the app-thunderbird run configuration with the fullDebug build variant (Build → Select Build Variant), and run it on the phone. Set up a mail account in it.
2. Select the app-thunderwren run configuration and run it on the watch.

Daily and Beta builds pair the same way: install fullDaily or fullBeta on the phone and the matching daily or beta build of app-thunderwren on the watch. Those need Thunderbird's signing keys, so locally only debug builds pair.

The companion and the notification quick reply are behind the feature flags wear_companion and wear_notification_quick_reply. They are on in Debug and Daily builds and off in Beta and Release for now. In debug builds, toggle them in Thunderbird's secret debug settings. While wear_companion is off, the phone removes its data from the watch the next time the watch asks for anything, and the watch says the companion is turned off.

Or from the command line, with both emulators running:

./gradlew :app-thunderbird:installFullDebug      # installs on the phone (pick it with ANDROID_SERIAL if needed)
./gradlew :app-thunderwren:installDebug          # installs on the watch

Tests and checks

./gradlew :feature:wear:companion:api:test :feature:wear:companion:internal:testDebugUnitTest
./gradlew :app-thunderwren:testDebugUnitTest     # view models, DI, app startup, and UI tests
./gradlew :app-thunderwren:detekt :app-thunderwren:spotlessCheck :app-thunderwren:lintDebug

Try the Tile and complication

• Tile: swipe to the tiles carousel on the watch and add "Unread Emails". To see senders and subjects on it with real mail, set Settings → General settings → Notifications → Lock Screen Notifications in Thunderbird on the phone to show them. The demo always shows them.
• Complication: long-press the watch face → Customize → pick a complication slot → ThunderWren / Unread Count.

Troubleshooting

• The watch says "Connect your phone": make sure the phone app is the fullDebug build from this repository (not fossDebug or the Play Store app), that the wear_companion feature flag is on, that it has at least one account, and that the emulators are paired. Opening Thunderbird on the phone once starts the companion.
• CI doesn't run on your fork: GitHub turns Actions off for forks. Enable it in the repository's Actions tab. The Build - ThunderWren Wear OS application job builds the watch app.
• Gradle sync fails with a version catalog error: pull the latest main. An earlier commit corrupted gradle/libs.versions.toml, which is fixed now.
• The Gradle daemon runs out of memory: the project reserves a 10 GB heap (org.gradle.jvmargs in gradle.properties). On machines with 16 GB of RAM or less, close other apps or lower -Xmx.

---

🗺️ Roadmap

• Wear OS app with Compose for Wear OS Material 3.
• Phone-first companion protocol and RFC (0010).
• Inboxes, mailbox switching, mail actions, open on phone, and a live Tile and complication.
• Demo mailbox for trying the watch app without a phone.
• Star and custom action order for Thunderbird's phone notifications on the watch.
• Translatable strings, screen reader labels, and a CI build job.
• Reply from the watch (voice, keyboard, or ready-made replies, sent by the phone), also from notifications.
• Respect Thunderbird's notification privacy settings on the Tile and complication.
• Swipe to archive or delete, Unread and Starred views, mark all as read, account monograms, and a richer Tile.
• Feature flags for the phone-side parts, Daily and Beta watch builds, and screens following Thunderbird's MVI pattern.
• Tested on paired phone and watch emulators in Android Studio.
• Tested on a Pixel 10 Pro Fold and a Pixel Watch 5, and fixed what that turned up: watch settings, swipe choices, smoother scrolling, and clearing the watch when the companion is turned off.
• Present on thunderbird/thunderbird-android#6969, the open Wear OS request.

For architectural guidelines, see docs/architecture/ and AGENTS.md. The original upstream README is preserved in README.upstream.md.

---

📜 License & Credits

ThunderWren is an open-source community project based on Thunderbird for Android and K-9 Mail. It is not an official Thunderbird or MZLA product.

Licensed under the Apache License, Version 2.0.