# Matcha is a Bubble Tea mail client with a daemon, a plugin market and a macOS helper > Matcha is an MIT licensed Go terminal email client built on the Charm Bubble Tea TUI, with support for multiple accounts, IMAP, JMAP, POP3 and Maildir, a built-in plugin marketplace with more than thirty community plugins, and a separate daemon that a macOS menu bar helper talks to. Releases are fast, with v1.1.0 and a nightly build published within days of each other. **floatpane/matcha** — A beautiful and functional email client for your terminal, built with Go and the charming Bubble Tea TUI library. Never leave your command line to check your inbox or send an email again! - Repository: https://github.com/floatpane/matcha - Website: https://matcha.email - Stars: 1,144 · Forks: 90 - Language: Go - License: MIT - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/floatpane-matcha ## The daemon is the part that separates Matcha from a single binary The repository layout is where the architecture shows. There is a daemon/ directory, a daemonclient/ directory and a daemonrpc/ directory, alongside the cli/, tui/ and view/ packages, and the dependency list includes github.com/floatpane/go-uds-jsonrpc, which is the transport for a JSON-RPC over a Unix domain socket. So Matcha is not one process that opens a socket to your IMAP server and renders it. There is a background daemon that owns the mail connections and the state, a client that talks to it over a local socket, and a TUI that draws what the daemon reports. That split is what makes the other features possible rather than decorative. The macOS menu bar helper is the clearest illustration. It lives in the menu bar, shows your unread count, posts native notifications with the Matcha icon on new mail, and lists your accounts so you can open Matcha in a terminal with a click. The README says it talks to the Matcha daemon, so no extra configuration is needed. That would be impossible if the mail connection only existed while a TUI was open, and it is the reason the daemon exists at all. The interfaces are the Charm stack, at version 2 of the libraries: charm.land/bubbletea/v2 for the model-update-view loop, charm.land/bubbles/v2 for the widgets, and charm.land/lipgloss/v2 for the styling. The project also uses floatpane/bubble-overlay, its own overlay library, and floatpane/termimage for rendering images in the terminal, which is how a rich HTML mail with inline images survives the trip into a character grid. ## Plugins install from a URL or a file, and come from a registry file The plugin system is the part of Matcha that most distinguishes it from the classic terminal mail clients it sits alongside, and the repository topics name those comparisons directly, listing aerc, mutt and pine. The commands are short. ```bash matcha marketplace # browse plugins in the TUI matcha install # install a plugin matcha config # configure an installed plugin ``` The marketplace is browsable from inside the TUI, and there is an online marketplace at docs.matcha.email/marketplace for browsing outside the terminal. The README says the system has more than 35 community plugins. What is notable is how a third-party plugin gets in. Anyone can submit their own plugin, and the route is to add an entry to plugins/registry.json and open a pull request. That is a deliberately low-friction path, and it also means the registry file is the trust boundary: the review happens on that JSON entry rather than on a separate review process for each extension. The dependency list shows what a plugin can reach. github.com/yuin/gopher-lua is a Lua interpreter embedded in the binary, which is the scripting substrate a plugin would use, and floatpane/go-keybind and floatpane/go-emoji-shortcode are the author's own libraries for key handling and emoji rendering. The plugin/ and plugins/ directories at the root, along with a SKILLS/ directory, are the surfaces the extension system occupies. ## IMAP, JMAP, POP3 and Maildir are all in the dependency list Mail clients fail on protocol coverage, so it is worth reading what Matcha actually implements rather than what it claims. For receiving, the list includes github.com/emersion/go-imap/v2 at a 2.0.0 beta, git.sr.ht/~rockorager/go-jmap for JMAP, github.com/knadh/go-pop3 for POP3, and github.com/emersion/go-maildir for local Maildir folders. For sending there is github.com/emersion/go-pgpmail, and for the surrounding protocol work github.com/emersion/go-message for MIME parsing, github.com/emersion/go-sasl for authentication, and github.com/ProtonMail/go-crypto for the OpenPGP implementation. The fact that the IMAP client is a 2.0 beta and the JMAP dependency is itself a pre-release tells you the project tracks the current generation of these protocols rather than the settled ones, and that some parts of the stack are less battle-worn than the rest. Encryption is a first-class concern rather than an afterthought. floatpane/go-openpgp-card-hl and cunicu.li/go-openpgp-card suggest hardware token support, go.mozilla.org/pkcs7 and floatpane/go-secretbox cover the message and key handling, and there is a pgp/ package in the tree. Credentials go to the operating system keychain through github.com/zalando/go-keyring, which is the right default for a mail client, and the gitmail/ directory points at Git-based email workflows. ## Rich content is sanitized before it is rendered Rendering HTML mail in a terminal is where a mail client usually either gives up or opens a hole. Matcha's dependency list shows it taking the second path seriously. The HTML sanitising library github.com/microcosm-cc/bluemonday is present, which is the standard Go tool for stripping dangerous markup from HTML, and github.com/PuerkitoBio/goquery is the HTML parser that sits alongside it. The rendering side has github.com/yuin/goldmark for Markdown, so a message that is plain text with Markdown formatting gets styled properly, and floatpane/termimage handles inline images by decoding them into the terminal's own image capabilities. The result is what the README calls support for rich content, and the demo GIF in the repository shows a mail client that is not a plain text pager. Two more details in the dependency list are worth flagging for anyone thinking about a professional mail client. github.com/wagslane/go-password-validator is there, which suggests password strength checks on the sending side, and github.com/google/uuid plus github.com/hashicorp/golang-lru/v2 point to an internal cache and identifier scheme for the daemon. The i18n/ directory, the theme/ directory and the view/ package together describe a client that is meant to be read for hours, not just glanced at, and the app/ and backend/ packages are where that composition happens. ## Logging flags go before the subcommand, version stays on -v The command line surface has one subtlety that will bite you if you guess. Matcha supports global logging verbosity flags before the main command or subcommand. ```bash matcha --verbose # enable verbose logging matcha -V daemon status # short form for verbose logging matcha --debug daemon status # enable debug logging ``` The placement is the point. The flag goes before the subcommand, so matcha -V daemon status turns on verbose logging for the daemon status command, and a reader who writes matcha daemon status -V is looking for a flag the parser does not expect there. There is also a compatibility note that matters if you have muscle memory from other tools. The existing -v and --version flags continue to print the Matcha version, which means the short form for verbose logging is -V and not -v. That is a deliberate choice, because -v is conventionally the version flag, and the project kept it that way. The macOS helper follows the same pattern with a subcommand of its own. ```bash matcha helper install # build & start the menu bar app (runs at login) matcha helper status # check whether it's installed and the daemon is up matcha helper uninstall # remove it ``` Building the helper uses the Xcode Command Line Tools' swiftc, the same requirement as matcha setup-mailto, so a macOS user without the command line tools installed will find that part of the setup blocked until they install them. ## Install is a Makefile target, and the release channels are four Building from source is a single command, and the Makefile is small enough to read in one screen. ```bash go build -o $(BUILD_DIR)/$(BINARY_NAME) . ``` The install target is more interesting, because it decides where the binary goes and how it identifies itself. It looks for an existing matcha on the path, uses that directory if it finds one, and otherwise falls back to INSTALL_DIR, which defaults to /usr/local/bin. It then derives the version from git describe --tags --abbrev=0, falling back to dev, takes the short commit hash, and stamps the current date into the binary through linker flags before installing with mode 755. The effect is a binary that reports which build it is, which is what you want when a bug report arrives. The release configuration is plural, and that is a signal. There are four goreleaser files: .goreleaser.yml, .goreleaser.rc.yml, .goreleaser.preview.yml and .goreleaser.nightly.yml, which correspond to a stable channel, a release candidate, a preview and a nightly. The tags confirm it. v1.0.1 on 2026-09-27, v1.1.0 on 2026-10-10, and then a nightly build tagged nightlyv0 on 2026-10-11, one day later, with a build number in its title. Around that, the packaging is broad: snapcraft.yaml for Snap, com.floatpane.matcha.yaml for a Flatpak-style desktop entry, a nix/ directory with flake.nix and a gomod2nix.toml, and a spellcheck/ directory. The screenshots and the demo GIF are generated from tape files with vhs, driven by .github/workflows/scripts/demo-sandbox.sh, and the demo is recorded against a fake Maildir inbox rather than a live server, which is a neat trick for keeping the documentation reproducible. ## MIT licensed, with the support burden spread across channels The licence is MIT, with the LICENSE file at the repository root, so you can use, modify and redistribute Matcha, including in commercial work, provided the copyright notice and the licence text are kept. That is a licensing fact rather than legal advice, and for a client that talks to your mail server it is the permissive end of the scale. The project is actively worked on. The repository is not archived, the default branch is master, and the last push was on 2026-10-19. The release sequence in two weeks, from v1.0.1 through v1.1.0 to a nightly, is the pace of a young project that has just found its audience. The support model is layered, and the layering tells you where to go. General suggestions and community discussion go to the Discord server, which the README recommends for exactly that, security issues have their own SECURITY.md policy in the repository, and urgent concerns have a support@floatpane.com address. Bug reports and feature requests have issue templates, one for each, linked at the bottom of the README, and CONTRIBUTING.md holds the contribution guidelines. The project is also funded by sponsorship through GitHub Sponsors and Open Collective, and the README invites commercial enquiries to us@floatpane.com, alongside a list of individual sponsors. There is a Trendshift badge and an Awesome TUI listing badge in the header, which are community signals rather than technical ones, but they do confirm that the project is discoverable in the terminal tooling ecosystem. ## Conclusion Matcha fits a developer who lives in the terminal and wants a mail client with a modern TUI, a plugin ecosystem and background fetching that keeps notifications working while the TUI is closed. It does not fit someone who needs a rich HTML reading experience, a calendar, or a phone client, and it does not fit a mail workflow that assumes a long-established single-binary tool. Before adopting it, read the documentation site at docs.matcha.email, try the plugin marketplace commands on a secondary account first, and check the nightly release policy, because the tag names show both a stable channel and an automatically numbered nightly build. ## FAQ ### What is Matcha and what is it built with? Matcha is a terminal email client written in Go using the Charm Bubble Tea TUI framework, with support for rich content, multiple accounts and advanced terminal features. It also ships a plugin system with more than 35 community plugins and a macOS menu bar helper. ### How do I install and browse plugins in Matcha? Use matcha marketplace to browse plugins in the TUI, matcha install to install one, and matcha config to configure an installed plugin. There is also an online marketplace at docs.matcha.email/marketplace, and third-party plugins are added by submitting an entry to plugins/registry.json. ### How do I turn on verbose logging in Matcha? The verbosity flags go before the main command or subcommand, for example matcha --verbose or matcha -V daemon status, and matcha --debug daemon status for debug logging. The -v and --version flags are unchanged and still print the Matcha version. ### What does the Matcha macOS menu bar helper do? It shows your unread count in the menu bar, posts native notifications with the Matcha icon on new mail, and lists your accounts so you can open Matcha in a terminal with a click. It talks to the Matcha daemon so no extra configuration is needed, and it is managed with matcha helper install, status and uninstall, requiring the Xcode Command Line Tools swiftc to build. ### Which mail protocols does Matcha support? The dependency list includes an IMAP client, JMAP, POP3 and Maildir for reading, and a PGP mail sender for sending, along with MIME parsing and SASL authentication libraries. It also carries OpenPGP support including hardware card support, and stores credentials in the operating system keyring. ## Sources - [floatpane/matcha on GitHub](https://github.com/floatpane/matcha) - [License: MIT](https://github.com/floatpane/matcha/blob/master/LICENSE) - [Project website](https://matcha.email) - [README](https://github.com/floatpane/matcha/blob/master/README.md) - [Releases](https://github.com/floatpane/matcha/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/floatpane-matcha