Omahub
← All plugins
G

HEY-CAL

by Gavin Nugent

One HEY panel: the top of the Imbox, with the next few calendar events pinned underneath. Summon with: omarchy-shell shell toggle nosignal.hey-cal

GitHub

Security review

Review recommended · 1 finding

Deterministic scan — not a security guarantee

Low
Risk level
Low
Analyzed commit
6801069
Scanned
1 month ago

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

  • Docs sudo README.md:137

    Command runs with sudo, elevating the process beyond the plugin environment.

    sudo rm /usr/local/bin/hey` for an old

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
6801069
Reviewed
1 month ago

The plugin is a read-only HEY mail/calendar panel that shells out to the official `hey` CLI with `--json` flags. The only finding is a `sudo rm /usr/local/bin/hey` command in the README's uninstall section, which is documentation-only and not part of any executable code. The QML code is transparent, non-obfuscated, and performs no destructive or hidden actions.

  • The deterministic scan flagged `sudo rm /usr/local/bin/hey` in README.md:137, but this is purely illustrative documentation for manually uninstalling the hey-cli binary and is not executed by the plugin.
  • The plugin writes to `~/.config/omarchy/shell.json` on first open to self-register a plugin reference; this is documented, idempotent, and limited to the user's own config file.
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/28allday/omarchy-hey-cal --enable
Productivity #bar #quickshell

HEY-CAL

Your HEY Imbox and your next few calendar events, in one panel on your Omarchy desktop. Press the shortcut, glance, press ↵ to open whatever you were looking at in the browser, and get back to what you were doing.

It is a native plugin for the Omarchy 4 desktop shell (omarchy-shell): an envelope in the bar, and a card that drops out of it.

<p align="center"> <img src="docs/panel.png" width="70%" alt="The panel: recent Imbox threads with the next few calendar events underneath"> </p>

The top of the card is the Imbox — the ten most recent threads, unread ones in bold with a dot, each showing who it is from, a snippet, the thread size and how long ago it moved. Underneath, in its own slab, is Up next: the next few things on your HEY Calendar, whichever calendar they live on.

Everything is read-only. Nothing here marks mail seen, archives, replies or sends, and nothing edits your calendar. The panel shows you what is there and gets out of the way.

Requirements

  • Omarchy 4 (the omarchy-shell desktop).

  • hey-cli — HEY's own command-line client, from 37signals. The plugin never sees your password or token; it asks the hey command for data the same way you would at a prompt.

    37signals now ships an official installer. On Omarchy, one line does it:

    omarchy-mise-install github:basecamp/hey-cli hey

    That line comes straight from hey-cli's own README, which also has one-line installers for macOS, WSL2 and Windows (the https://hey.com/install-cli script) if you're setting up a non-Omarchy machine. Using mise directly instead, it's MISE_MINIMUM_RELEASE_AGE=0 mise use -g github:basecamp/hey-cli — the override skips mise's 24-hour hold on brand-new releases. The AUR hey-cli package tracks upstream properly again as of 1.2.1. Prefer verifying by hand? Every release publishes tarballs, .deb/.rpm/.apk packages and a checksums.txt; and once any of these is installed, hey upgrade moves it to the latest release.

    One thing to avoid: hey is not a unique name — the AUR's hey-bin and hey-git package an HTTP load generator that also installs a binary called hey. Only Basecamp's will do here, and the panel checks: it identifies the binary before passing it any arguments, and says plainly if the hey it found is the wrong one.

    However you install it, sign in afterwards — browser-based OAuth, no password ever reaches this plugin:

    hey auth login

    hey auth status should be happy before you open the panel. If it isn't, the panel tells you so rather than showing an empty list.

  • jq, which is almost certainly already installed.

The panel speaks both generations of the CLI and picks by what the installed hey actually offers: the 1.x surface (calendar / event list — one call, every calendar, real calendar names) and the 0.x one (calendars / recordings). Everything it parses — .data.postings, the event fields, app_url, edit_url — was verified live against the v1.2.1 release binary and against v0.1.1/22aeea7, with both paths producing identical output on the same account. The parser is defensive, so a shape change degrades to an error note rather than a broken panel, but it can't self-diagnose: if a fetch comes back wrong after you move the CLI forward, that is the first thing to suspect.

Install

Installing the plugin does not install hey-cli — a plugin install is a git clone, so it cannot place binaries or pull packages. Set the CLI up first, or the panel will open and tell you it can't find it.

omarchy plugin add https://github.com/28allday/omarchy-hey-cal.git
omarchy-shell shell rescanPlugins
omarchy plugin enable nosignal.hey-cal --section right

That puts an envelope in the right-hand side of your bar. Click it to open the panel.

To reach it from the keyboard, add a binding to ~/.config/hypr/bindings.lua:

o.bind("SUPER + ALT + H", "HEY", "omarchy-shell shell toggle nosignal.hey-cal")

Bindings are picked up as soon as you save the file.

Removing it

To take the icon out of the bar but keep the plugin installed:

omarchy plugin disable nosignal.hey-cal

To remove it altogether:

omarchy plugin remove nosignal.hey-cal

That deletes the clone and takes the icon back out of bar.layout.

One line survives it: the {"id": "nosignal.hey-cal"} entry in plugins[] described below. omarchy plugin remove clears the first entry it finds for a plugin, and this one has two, so it clears the bar icon and stops. The leftover is inert — the shell skips an entry whose plugin is not installed — but if you would rather the file were tidy:

cfg=~/.config/omarchy/shell.json
jq 'del(.plugins[]? | select(.id == "nosignal.hey-cal"))' "$cfg" > "$cfg.tmp" &&
  mv "$cfg.tmp" "$cfg"

Two more things removal can't clean up, because they aren't the plugin's to touch:

  • The keybinding, if you added one — that line is yours, in your bindings.lua. Delete it or it will toggle a panel that is no longer there.
  • hey-cli, which you installed separately and may well be using outside this plugin. Remove it the way you installed it — mise uninstall github:basecamp/hey-cli for the mise/omarchy-mise-install route, your package manager for a package, or sudo rm /usr/local/bin/hey for an old manual install — and run hey auth logout first to drop its stored session: the keyring entry, or ~/.config/hey-cli/credentials.json on a box where it fell back to the plaintext file.

Using it

Key Does
↓ ↑ or j k Move the cursor. It runs through the mail and straight on into the agenda.
Home End First row / last row.
↵ Open the selected row in your browser — a mail thread at that thread, an event at that event.
r or F5 Fetch again.
Esc or q Close. Clicking outside the card closes it too.

The mouse does the same things: hover to move the cursor, click a row to open it.

How much it shows

Ten threads and four events, which is what fits without the card becoming a second inbox. If the Imbox has more, a line under the list tells you how many are waiting.

Both numbers live at the top of Panel.qml and are a one-line change each:

property int mailLimit: 10
property int eventLimit: 4

Only events that are still ahead of you are listed. A timed event stays up until it ends; an all-day event stays up for the whole of its day.

What it does on your machine

Worth knowing before you install anything that can read your mail:

  • It fetches only when you open it. Nothing polls. Close the panel and it makes no requests at all; leave it open and it still makes none until you press r. The bar icon is a static icon, not a live unread badge — a badge would mean hitting HEY on a timer, which is the one thing this deliberately does not do.
  • It reads, it never writes. The only commands it runs are hey box imbox, hey calendars and hey recordings, all with --json.
  • It stores nothing itself. No cache, no mail on disk, no credentials — your HEY session belongs to hey-cli and is never read here. Where that session actually lives depends on your machine: hey-cli keeps it in the system keyring when one is available, but falls back to a plaintext file, ~/.config/hey-cli/credentials.json (created 0600), in two cases. When no keyring is reachable, hey warns on stderr — a stream this panel's own fetches don't show you, so the panel watches for that warning and puts a notice in the card whenever a fetch triggers the fallback. When HEY_NO_KEYRING is set, the switch is silent — no warning anywhere, nothing for the panel to surface either. And because every hey command refreshes an expiring token automatically, even this plugin's read-only fetches can cause hey-cli to rewrite that file. If the plaintext fallback bothers you, make sure a Secret Service keyring is running before hey auth login — hey doctor reports which store is in use. (Behaviour verified in the source of the v1.2.1 release — internal/auth/store.go — and unchanged since v0.1.1/22aeea7: same warning text, same silent HEY_NO_KEYRING path, same fallback file.)
  • It writes one line to your shell config. The first time the panel opens it adds {"id": "nosignal.hey-cal"} to the plugins[] array in ~/.config/omarchy/shell.json, if it is not already there. This is what keeps the keyboard shortcut working when the bar icon is not in the bar — without it, removing the icon silently kills the shortcut. It is idempotent, it adds only that one entry, it never removes anything, and it writes through a temporary file. Removing the plugin leaves this one line behind — see Removing it for why, and the one command that clears it.
  • Opening a row launches your browser, whichever one you have set as default, through Omarchy's own omarchy-launch-browser. Only https:// links are ever passed on.
  • Subjects, senders and snippets are rendered as plain text, never as markup, so nothing in an email can draw or load anything in your bar.

Scope

  • Imbox only. Not the Feed, Reply Later, Set Aside, Paper Trail or Bubble Up. If it is not in the Imbox it is not here.
  • Events only. Habits and todos are not shown; this is an agenda, not a task list.
  • No composing. Open the thread in HEY to reply.

Related

Two single-purpose plugins do the halves separately, if that suits you better: one is the Imbox on its own, the other the full 30-day agenda grouped by day. This one is the merge of the two.

Licence

MIT — see LICENSE.

Not affiliated with, endorsed by, or connected to Basecamp or HEY.