Omahub
← All plugins
M

Porthole

by Marko Stankovic

Pin a live cropped view of any window — always on top, on every workspace

GitHub

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
1b09d6d
Scanned
1 month ago

No potentially dangerous behavior detected in the analyzed commit.

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

This is a legitimate screen-capture overlay plugin that pins a cropped view of a window. The code is well-structured, uses safe practices (e.g., forcing plain text to avoid rich-text injection, writing test grabs only to XDG_RUNTIME_DIR), and contains no suspicious or destructive operations. The deterministic scan found no issues.

  • The plugin captures window content, which could be sensitive, but this is the intended functionality and requires explicit user action to pin a window.
  • The included test scripts spawn processes (alacritty, hyprctl) but these are separate dev harnesses and not part of the plugin runtime.
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/marko-builds/porthole --enable
Productivity #Hyprland #quickshell #workspaces

Porthole

Pin a live, cropped view of any window as a small always-on-top porthole. It stays on every workspace and keeps updating even while the source window sits on a hidden one. PowerToys Crop and Lock, native to Omarchy.

You park a build, a CI log, or a render on workspace 5, then flip back every minute to check on it. Porthole ends the flipping: crop the two lines that matter and keep them in the corner of your screen while you work.

Porthole pinned over a workspace

Install

omarchy plugin add https://github.com/marko-builds/porthole --enable

Remove it the same way:

omarchy plugin remove io.github.marko-builds.porthole

Use

Plugins cannot register keybinds, so bind the picker yourself in ~/.config/hypr/bindings.lua:

o.bind("SUPER + ALT + P", "Porthole", "omarchy-shell shell summon io.github.marko-builds.porthole")
  1. Pick a window. Arrows and Enter work, so does the mouse.
  2. Drag a rectangle over the live preview and click Pin region, or press Enter to pin the whole window.
  3. The porthole appears bottom right. ESC steps back. Summoning the picker again lists every pinned porthole with an Unpin button.

On the porthole itself:

  • Drag moves it. It stops at the screen edges.
  • Scroll resizes it, 200 to 1400 px wide.
  • A plain click jumps to the source window.
  • Hover shows the title bar with pause and close.
  • When the source window closes, the porthole says so. Click it to unpin.

How it works

Hyprland keeps rendering a window for capture even when it sits on a hidden workspace; screen sharing depends on the same mechanism. Porthole requests that capture through Quickshell's ScreencopyView with the picked toplevel as its source, then shows only the rectangle you drew: the full frame is drawn at crop scale inside a clipping item, shifted so your region lands at the origin.

Each porthole is a fullscreen transparent layer-shell window whose visible card is an inner item. Drag becomes plain item math instead of a feedback loop through the compositor, and an input mask keeps every pixel outside the card click-through. The card never takes keyboard focus.

Limits, stated

  • A shell restart (theme change, plugin update) drops all pinned portholes. Re-pin by hand; persistence is not in v1.
  • The crop is fixed buffer pixels. If the source window resizes, the region can slide off the content it was aimed at.
  • SUPER+W cannot close a porthole. Layer surfaces are not windows to Hyprland. Use the click, the close button, or the picker's Unpin list.
  • Sources on hidden and special workspaces keep updating (verified in the selftest). Minimized windows are untested.

Dev harnesses

selftest.qml drives the whole flow headless: it spawns a target window, pins a crop, moves the source to a hidden workspace, proves the frames still advance, kills the source, and checks the dead state. probe/probe.qml is the original capture feasibility probe. Both run standalone beside the live shell and need alacritty for the throwaway target window:

quickshell -p selftest.qml

Output lands under $XDG_RUNTIME_DIR (porthole-selftest/ and porthole-probe/).

License

MIT