Mekubari

The quiet cue for the dialog waiting somewhere else.

Mekubari is an attention service for Omarchy Quattro. When an application leaves a high-confidence modal-style companion window waiting on a hidden Hyprland workspace, Mekubari places one small slip at the edge of the screen you are using:

Chromium needs your attention — Visit

Click Visit and Mekubari asks the compositor to activate that exact dialog. If the dialog is handled, closed, or brought onto an active workspace another way, the slip disappears. There is no inbox and no history to clean up.

The name is the Japanese word 目配り (mekubari): keeping an attentive eye on several places.

Why it belongs in the shell

This is not a notification parser or another task switcher. Mekubari combines compositor-level facts an ordinary application should not guess at:

• Wayland supplies native parentage when the compositor exports it.
• On current Hyprland, which does not export that optional parent event, Mekubari requires a recently focused floating secondary window plus a non-floating companion with the same bounded application ID, positive process ID, and workspace.
• Hyprland identifies whether that workspace is currently hidden.

Mekubari says nothing unless the full relationship is present. Floating state alone, an urgent bit, a suspicious title, or an application's custom wording is never enough.

The restraint is the feature

• High-confidence companions only. No title heuristics or guesses from window size, urgency, or application wording; a floating window alone never qualifies.
• Hidden workspaces only. A dialog already visible on any active monitor does not produce a cue.
• One slip, not a center. Mekubari shows the newest eligible dialog and keeps no queue, history, badges, or archive.
• No dialog text. Mekubari never accesses title fields, file paths, account names, prompts, or dialog contents, and none are rendered, logged, copied, or persisted.
• Local and event-driven. There is no network access, telemetry, timer-based compositor polling, background process, or separate daemon.
• Fail closed. Missing relationship, process, application, workspace, focus, floating, or Hyprland mapping data means no cue.

Dismiss the slip with its × button when you want to leave that dialog waiting. It stays dismissed only while that exact dialog exists; once the window closes, the in-memory suppression disappears.

Requirements

• Omarchy Quattro 4.0.0.alpha or a compatible later release
• Hyprland and Quickshell with foreign-toplevel and Hyprland toplevel metadata support, as provided by Omarchy

Mekubari has no separately installed runtime dependencies.

Install

Once the RegionallyFamous repository is published, add it with:

omarchy plugin add https://github.com/RegionallyFamous/mekubari.git

Then enable the service:

omarchy plugin enable io.github.regionallyfamous.mekubari

Mekubari starts with the shared Omarchy shell and needs no keybinding.

Preview the attention slip

You can render a privacy-safe sample without opening or focusing any application:

omarchy-shell mekubari preview

The preview uses the same bounded app-label path and exact interface as a real cue. Click Visit to close it, or dismiss it from the command line:

omarchy-shell mekubari dismiss

Inspect only the safe public state:

omarchy-shell mekubari state

The response reports whether a cue is visible, whether it is a preview, the bounded display label, and whether an activation request was delayed. It never returns a window address, dialog title, workspace name, path, prompt, or contents.

How it works

Mekubari subscribes to Quickshell's existing ToplevelManager and Hyprland models inside the shared shell process. Changes to toplevel parentage, activation, mapping, Hyprland client metadata, screens, and workspace activity coalesce into a short event-driven refresh. Focus changes ask Quickshell to refresh its in-process Hyprland model; there is no timer-based polling or child process. Mekubari inspects at most the newest 256 toplevel objects per refresh.

A candidate must have all of the following:

1. a floating window that was most recently focused;
2. either a native Wayland parent or a non-floating same-process companion with the same bounded application ID and workspace;
3. a valid mapped Hyprland window address;
4. a mapped, inactive Hyprland workspace; and
5. no active or locally dismissed state.

The window address is an internal identity only. Quickshell's unprefixed hexadecimal form and Hyprland's 0x form are canonicalized to one validated, 64-bit-style identity, kept in memory, and never displayed or returned over IPC. Process IDs and numeric focus order are used only for equality and range checks and are never displayed, returned, logged, or persisted. The only compositor-controlled string admitted to the interface is the application ID. Mekubari rejects it above 128 UTF-16 code units or 256 UTF-8 bytes, removes controls and whitespace runs, converts it to a display label capped at 40 characters, and renders it as plain text. Unknown or rejected IDs become the generic label “An app.” The code never accesses title fields.

The resource budget is fixed at every plugin-controlled boundary: only the newest 256 toplevels receive watchers or enter candidate inspection; at most 256 canonical 18-character addresses are retained for in-memory dismissal; application IDs are rejected before normalization above the limits described above; and IPC returns only four fixed fields with a label capped at 40 characters. The preview command accepts no external text. Mekubari starts no child process and reads no file or network response.

Clicking Visit calls Wayland's toplevel activation request directly. Mekubari does not synthesize shell commands, interpolate window metadata into a process, change workspaces itself, or close anything. If the compositor ignores the request, the slip remains and offers a retry.

Privacy and security

Mekubari stores no files and requests no privileges. It does not install packages, edit Hyprland configuration, add keybindings, register a system service, contact a server, load remote code, or retain application activity.

The plugin runs unsandboxed inside omarchy-shell, like every Quattro shell plugin, so its small source tree is intentionally auditable: one QML service, one pure JavaScript policy model, deterministic tests, and a validation script.

Test

Run the free local checks from the project root:

./tools/lint-manifest.sh .
node --test test/*.test.js

On Omarchy Quattro, also run the host validator and QML linter:

omarchy plugin validate .
qmllint -I "$OMARCHY_PATH/shell" Mekubari.qml

The included guest acceptance test installs and enables the exact repository payload, exercises the preview with real pointer input, opens a native parented Wayland dialog on one workspace, switches away, verifies Mekubari appears without exposing the dialog title, clicks Visit, proves the compositor returns to the dialog, then checks disablement, restart persistence, removal, and pixel-clear dismissal.

Disable or remove

Pause Mekubari without deleting it:

omarchy plugin disable io.github.regionallyfamous.mekubari

Remove it completely:

omarchy plugin remove io.github.regionallyfamous.mekubari

There is no plugin-owned state directory or service to clean up.

License

MIT