Omahub
← All plugins
R

Mail

by Roy McKenzie

Two-pane IMAP client on the bar: unread count, conversations, and compose.

GitHub

Security review

Review recommended · 1 finding

Deterministic scan — not a security guarantee

Low
Risk level
Low
Analyzed commit
a9bc751
Scanned
2 weeks ago

Flagged patterns appear only in documentation files (README / docs) — descriptive examples, not executable code.

  • Docs external_hosts DEVELOPMENT.md:58

    Downloads or connects to an external HTTP(S) host.

    git clone https://github.com/roymckenzie/omarchy-mail.git

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

Low
AI risk level
Low
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
a9bc751
Reviewed
2 weeks ago

The plugin is a legitimate IMAP/SMTP mail client widget. The only deterministic finding is a git clone command in DEVELOPMENT.md, which is documentation for developers and not executed at install time. The sampled code shows no obfuscation, no destructive commands, and credentials are handled via the system keyring with a mode-600 config file.

  • The helper process reads account passwords from the user's keyring via secret-tool and sends them to the configured IMAP/SMTP servers; this is expected behavior for a mail client but means the plugin handles sensitive credentials.
  • The plugin stores account metadata in ~/.local/state/omarchy/settings/omarchy-mail.json and caches mail locally; the README states passwords are not stored in that file, and the code uses secret-tool for password storage.
  • The deterministic scan flagged a git clone URL in DEVELOPMENT.md; that is developer documentation, not part of the install path, so it does not increase risk.
How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/roymckenzie/omarchy-mail --enable
Productivity #bar #quickshell

Mail

Bar widget for Omarchy. Unread count on the bar, two-pane IMAP client in the panel.

Plugin id: io.github.roymckenzie.omarchy-mail

With a saved account, the helper lists the latest 50 envelopes over IMAP, searches on the server, and fetches bodies when you open a thread. Envelope lists are cached on disk so the panel can open immediately; IMAP IDLE refreshes in the background and new mail posts an Omarchy notification. Until an account is saved, the panel is empty.

Install

omarchy plugin add https://github.com/roymckenzie/omarchy-mail.git --enable

--enable places the widget on the right of the bar. Open it with a left click, then add an IMAP/SMTP account (gear or s).

The helper is bin/omarchy-mail-helper, a Python 3 script (stdlib only: no pip, no virtualenv). omarchy plugin add is enough; there is no compile step.

Requirements

  • Omarchy with omarchy-shell
  • An IMAP and SMTP mailbox (host, ports, username, password)
  • secret-tool (libsecret) for passwords in the user keyring
  • python3 (stdlib imaplib / smtplib / email)
  • xdg-desktop-portal (GTK 3 fallback) for the attach picker

The plugin does not use sudo. It talks to your mail hosts from the helper process, stores account metadata in ~/.local/state/omarchy/settings/omarchy-mail.json (mode 600), and caches envelopes in ~/.local/state/omarchy/mail/cache/. Passwords never go in that file.

Configure

omarchy bar move io.github.roymckenzie.omarchy-mail --section right

General settings can make Mail the default mailto: handler. A Hyprland bind of Super+M can toggle the panel (not installed by the plugin):

o.bind("SUPER + M", "Mail", "omarchy-shell shell toggle io.github.roymckenzie.omarchy-mail")

Usage

  • Left click opens the panel
  • ? shortcuts
  • / search (IMAP Subject/From/To/Cc, then BODY if nothing matches)
  • Gear (or s) opens account settings
  • Mailbox icon left of the account chips (Inbox / Sent / Drafts / Archive / Junk / Trash)
  • j / k move, h / l list or message, Enter open
  • r reply, a reply all, f forward, c compose
  • e archive (or move back to Inbox), ! junk (or not junk from Junk)
  • x trash (deletes forever from Sent, Trash, and Junk), u toggle unread
  • g i / g s / g d / g e / g b / g t jump to inbox, sent, drafts, archive, junk, trash
  • Esc hides address suggestions, then cancels compose/reply, then closes the panel
  • Ctrl+Enter sends, Ctrl+S saves a draft
  • Middle click (or 0) reloads the current folder

Reply, reply-all, forward, and compose are plaintext. Reply-all puts the sender in To and everyone else (minus you) in Cc. Compose Cc/Bcc fields expand from chips on the To row. Forward quotes the thread and can carry its attachments. An in-progress compose or reply is kept if you close the panel.

Attachments on a thread open with a click and save to Downloads on right-click. Compose and reply attach through an out-of-process portal picker (the panel closes for the dialog, then restores the draft). Compose sends over SMTP and appends a copy to Sent. Save Draft appends to the account Drafts folder. With more than one account, click From in compose to pick which address sends the message; Send and Save Draft use that account's SMTP, Sent, and Drafts. General settings can mute new-mail notifications and choose the default From account when All is selected. Opening a draft uses the compose pane; Sent is a reading pane.

The To/Cc/Bcc fields autocomplete from addresses harvested from IMAP envelopes (From on inbox, To/Cc on sent). HTML mail is rendered as a small block model (paragraph, heading, quote, list) — not a web view.

Architecture and local development: DEVELOPMENT.md.

Remove

omarchy plugin remove io.github.roymckenzie.omarchy-mail

This removes the plugin. Account settings, the keyring entry, and the envelope cache are left in place.

License

MIT. See LICENSE.