mailbox.
At home on Omarchy

Your mail.
Your time.
Everywhere.

A fast, agent-oriented CLI and background daemon for email, calendars, tasks, habits, and contacts. Instant local reads from an offline SQLite mirror, write-through consistency, server-side Sieve routing—and three dedicated visual interfaces designed for the Omarchy desktop.

Get mailbox Read the source ↗
Daemon & CLI Qt Desktop Client Calendar & Mail Widgets Agent Skills

Free & open source · Linux · MIT

✦ mailbox LIVE GUI

Inbox

PREVIOUSLY SEEN 1
CX
Cinemax — Your tickets are ready · noreply@cinemax.com
Booking confirmed for Friday 19:30 · Seat H12...
1 Sep
🔖
AC
Plan · Acme Corp

Interactive preview · authentic Omarchy Qt client, Quickshell widgets & CLI.

01 Instant SQLite mirror 02 Standalone daemon & CLI 03 Dedicated Omarchy GUI 04 Server-side Sieve
01 / THE HEADLESS FOUNDATION

The daemon and the CLI operate 100% independently.

No display server, Qt, or desktop environment required. The background daemon owns all server connections and maintains an offline SQLite mirror; the CLI answers queries in ~1ms with zero network latency.

The SQLite Mirror

A disposable local read model holding mail, events, todos, and contacts. Reads answer in ~1ms directly from SQLite; dropping it loses zero data.

~/.local/share/mailbox/mirror.db

Durable Outbox

Outgoing messages stage in a disk-backed queue before SMTP submission. Network disruptions hold mail safely for retry rather than dropping or duplicating.

held queue · zero lost mail

Zero-Click Pickups

Recognizes 2FA codes and magic links gated on the subject line. Copies the token to your clipboard, sends a desktop notification when collected, marks it read, and auto-trashes it after ~15m.

clipboard · notification · auto-trash ~15m

First-Class Agent Support

Every command supports structured --json with freshness metadata (behind: false). Discovery via mailbox commands.

mailbox commands · skill/SKILL.md
02 / THE VISUAL INTERFACES

Three dedicated clients over the daemon socket.

The GUI is not a monolithic program. It is three unbundled tools built for the Omarchy desktop, each interfacing directly with the daemon's Unix socket over NDJSON.

1. Desktop Mail Client (mailbox-gui)

A HEY-style desktop client in Qt 6. Single view, content first: Inbox split into New for you and Previously seen, The Feed, Paper Trail, and Screener. Fanned card stacks for Set Aside and Reply Later ride the bottom. Includes Basecamp's Lexxy rich text composer, 5-second undo send, and Dark Reader mail theming.

make install-gui · ~/.local/bin/mailbox-gui

2. Calendar Widget (mailbox.clock)

A Quickshell top bar clock and interactive popup window. Displays the monthly calendar grid with event dots, a year progress bar, upcoming meetings with one-click launch buttons (Join Zoom, Join Teams), weekly task checklists, and a natural language event entry pane.

plugins/mailbox.clock · Quickshell bar widget

3. Mail Notification Bar (mailbox.email)

A dynamic Quickshell bar icon that appears only when unread inbox mail arrives. Collapses completely when caught up so your bar stays distraction-free. The dropdown lists new arrivals for a quick glance and opens the message in the desktop client with one click.

plugins/mailbox.email · Quickshell notification dropdown
03 / ARCHITECTURE & UNIX SOCKET

Sub-millisecond speed without sync drift.

Instead of opening remote network connections on every command, a single long-lived daemon owns the servers and the Mirror. The CLI, GUI, and widgets all speak the same NDJSON protocol.

Clients & Interfaces mailbox CLI · mailbox-gui · mailbox.clock · mailbox.email · AI Agents
Unix Domain Socket (NDJSON) $XDG_RUNTIME_DIR/mailbox.sock
mailbox daemon SQLite Mirror (Reads) + Durable Outbox (Writes)
Remote Mail & DAV Servers IMAP · SMTP · CalDAV · CardDAV · ManageSieve

Local reads answer from SQLite in ~1ms. Modifying commands write through to the server before acknowledging with exit code 0.

04 / MODULAR INSTALLATION

Install what you need.

Build and install only the components you want. Everything runs locally under your systemd user session with zero cloud intermediaries.

Requires Linux and Go 1.22+. The desktop client optionally requires Qt 6 with WebEngine; the bar widgets require Quickshell / Omarchy.

Full command guide & manual ↗
Terminal Build and install all components
git clone https://github.com/parnoldx/mailbox-cli.git && cd mailbox-cli && make install-all

  1. Run the interactive setup wizard. Discover mail folders, calendars, address books, and save secure config: mailbox setup.
  2. Enable the background daemon. Activate the systemd socket: systemctl --user enable --now mailbox.socket.
  3. Open your tools. Run mailbox status in your shell, launch mailbox-gui, or use the Omarchy bar widgets.

Modular targets: make install (CLI & daemon only), make install-gui (Qt client), make install-plugins (Omarchy widgets), or make skill (AI agent skills).

05 / PRACTICAL DETAILS

Frequently asked questions.

Can I run mailbox purely headlessly without any GUI?

Yes. The CLI and daemon are pure Go and have zero GUI or display server dependencies. You can run them on remote servers, headless devboxes, or in automated cron/agent environments with make install.

How do the GUI components communicate with the daemon?

All three GUI components (the Qt client, the calendar widget, and the email notification bar) communicate over a local Unix domain socket ($XDG_RUNTIME_DIR/mailbox.sock) using newline-delimited JSON (NDJSON). They do not open network connections or parse databases directly.

How does the local SQLite mirror stay synchronized?

The background daemon listens on IMAP IDLE and pushes sync cycles to remote servers. When you run a read command, it returns in ~1ms directly from SQLite. If the daemon is temporarily catching up, it answers with behind: true metadata instead of stalling.

What is a "Pickup" and why does it bypass normal mail routing?

A login code or magic link is not mail to triage, it is a token to collect: worth thirty seconds and then worth nothing. The daemon gates on the subject line, copies the token to your clipboard, sends a desktop notification when it is collected, marks it read so it never alerts you again, and moves it to Trash after about 15 minutes.

How does live Omarchy theme morphing work?

The desktop client includes a native C++ theme monitor (OmarchyTheme) that watches ~/.local/state/omarchy/current/theme/colors.toml. The instant you change your Omarchy theme (e.g. omarchy theme set "Gruvbox"), all window colors morph live with zero restart.

Does mailbox store credentials or messages on a third-party server?

Never. Mailbox has no cloud relay, hosted server, or analytics. Your machine connects directly to your own configured mail, CalDAV, CardDAV, and Sieve servers over encrypted TLS.