Omahub
← All plugins
Y

Screen Time

by Yassine Grairi

Local app usage tracking with daily limits that cover the over-budget app's window until midnight

GitHub

Security review

Review recommended · 3 findings

Deterministic scan — not a security guarantee

Medium
Risk level
Medium
Analyzed commit
1cdc38f
Scanned
1 month ago
  • medium external_hosts Service.qml:22

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

    curl -fsSL https://<host>/favicon.ico
  • medium external_hosts browser-extension/install.sh:83

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

    curl -X POST http://127.0.0.1:8765/ -d '{\"host\":\"test.com\"}' && cat $STATE_DIR/browser-urls.json"
  • Docs external_hosts README.md:45

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

    git clone https://github.com/yass-gr/omarchy-screen-time.git ~/.config/omarchy/plugins/yass-gr.screen-time

Automated analysis only — not a security guarantee.

AI advisory review

Review recommended

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

Low
AI risk level
Low
Recommendation
review
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
1cdc38f
Reviewed
1 month ago

The deterministic scan's medium is mostly driven by README/manual-install examples and a localhost verification curl; the only real outbound traffic is a sanitized favicon fetch from Service.qml for visited hosts. I found no obfuscation, credential theft, hidden persistence, or destructive install behavior, so the practical risk is low, though the network/privacy behavior warrants a human look before publishing.

  • Favicon fetching in Service.qml makes outbound HTTPS requests to arbitrary visited hosts (sanitized, but allows single-label and private IP hosts); this is a privacy side effect not clearly disclosed in the README.
  • The optional browser extension uses a 127.0.0.1:8765 bridge, and the /token endpoint is unauthenticated, so any local process or page able to reach it can interact with the bridge; this is low-impact and local-only, but should be documented.
  • browser-extension/install.sh writes native-messaging host manifests and does not remove them on plugin uninstall; explicit behavior, but a cleanup consideration.
  • The README and install.sh curl/git-clone snippets flagged by the scanner are documentation or localhost verification commands, not runtime threats.
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/yass-gr/omarchy-screen-time --enable
Productivity #bar #quickshell

Omarchy Screen Time

Screen time tracking with hard daily limits for Omarchy v4.

Screen Time shows how many hours your day actually gives to each app. A small widget in your bar keeps today's running total in view, and the dashboard breaks it down by app, by website, and even by terminal command.

Give any of them a daily budget. When Firefox burns through its two hours, a cover appears over Firefox's window only—nothing is killed, and the rest of your desktop stays fully usable. The cover shows the time until reset and a Close app button; switch away and it lifts, refocus and it's back. You pick the numbers; the plugin does the enforcing.

<p align="center"> <img src="screenshots/smallpanel.png" alt="Compact widget" width="330" /> <img src="screenshots/bigpanel.png" alt="Expanded dashboard" width="330" /> </p>

What it tracks

  • Focus time only. A window sitting behind another window earns nothing.
  • Idle time doesn't count either. Counting stops after 60 seconds without input by default, and gaps over five minutes (suspend, crash) count as zero instead of as hours.
  • Firefox time splits into sites like youtube.com. Foot or kitty time splits into the commands you ran. Title parsing does this with nothing installed; the optional extension below makes it exact.
  • Plumbing apps you never chose to open, like portal wrappers and xwaylandvideobridge, never show up in totals or lists.
  • Window titles are thrown away before anything is written to disk. A stored row is an app id, a display name, seconds, and a session count, pruned after 90 days.

Dashboard

Today's total beside yesterday's, the last seven days as clickable bars, and your most-used apps with rings showing what's left of their limits. Step through days with ‹ ›. Colors come from your Omarchy theme, light themes included. There is nothing to configure.

Expanded dashboard

Same panel in other themes:

<p align="center"> <img src="screenshots/othertheme1big.png" alt="Theme 1" width="210" /> <img src="screenshots/othertheme2.png" alt="Theme 2" width="210" /> <img src="screenshots/othertheme3.png" alt="Theme 3" width="210" /> </p>

Install

omarchy plugin add https://github.com/yass-gr/omarchy-screen-time.git --enable

Manual clone works too:

git clone https://github.com/yass-gr/omarchy-screen-time.git ~/.config/omarchy/plugins/yass-gr.screen-time
omarchy-shell shell rescanPlugins && omarchy plugin enable yass-gr.screen-time

Enabling starts the tracker inside your running omarchy-shell process, so there is no second Quickshell instance eating RAM. The widget lands on the right side of the bar. Move it with omarchy bar move yass-gr.screen-time --section left|center|right, click it to open the dashboard.

Requires Omarchy 4.

That's the whole install. Optional extra: exact per-site browser tracking needs a tiny companion extension — see Exact site time below.

Limits

Set a timer from any row's ring, from the overflow menu, or from a terminal:

omarchy-shell screen-time setLimit firefox 2700        # 45 minutes a day
omarchy-shell screen-time setRuleEnabled firefox false # pause without deleting
omarchy-shell screen-time deleteLimit firefox          # remove entirely

Limits run from 60 seconds to 24 hours. When one runs out you get a single notification for the day, and the app's window gets covered until midnight—the rest of the screen stays clickable and compositor keybinds keep working. Disabling or deleting the rule unblocks the app immediately. Deleting history leaves rules alone; deleting rules leaves history alone.

Keyboard

The dashboard works without a mouse. Hovering and arrow keys move the same cursor.

Key Action
↑ ↓ Move between apps; collapse from compact view
Enter Expand dashboard, expand group, or open the timer editor
← → Previous or next day
n / e New timer; edit focused timer
Delete Remove focused timer
o Overflow menu
/ Jump to first row
Esc Back out

In the timer editor, ← → pick the hour/minute/second drum and ↑ ↓ spin it. Tab reaches the buttons.

Exact site time (optional)

Without the extension, sites come from window titles, which sometimes guess wrong. The companion WebExtension reports the real host:

bash ~/.config/omarchy/plugins/yass-gr.screen-time/browser-extension/install.sh

Load browser-extension/firefox/manifest.json through about:debugging in Firefox or Zen, or load the browser-extension/chrome/ folder unpacked through chrome://extensions in Chrome or Brave. The extension sends exactly one string, the bare hostname, to a bridge listening on 127.0.0.1:8765. No URLs and no page contents ever leave the browser, and the bridge rejects requests that lack the token generated at install time.

Scripting

omarchy-shell screen-time status    # loaded, today's total, idle state, exhausted apps
omarchy-shell screen-time today     # per-app list with remaining time
omarchy-shell screen-time week      # last seven days
omarchy-shell screen-time clearHistory yes

Usage lives in ~/.local/state/omarchy-screen-time/usage.json, kept for 90 days. Settings and rules live in ~/.config/omarchy/screen-time.json.

Development

node tests/run-tests.mjs      # unit tests for the pure JS core
omarchy plugin validate .     # manifest check
qmllint -I /usr/share/omarchy/shell *.qml

AGENTS.md documents the dev loop, including a symlink quirk that will otherwise cost you an hour of rescan-and-pray.

Removal

omarchy plugin remove yass-gr.screen-time
rm -f ~/.config/omarchy/screen-time.json
rm -rf ~/.local/state/omarchy-screen-time

Removing the plugin stops tracking immediately. The files above are data only; delete them whenever you like.

License

MIT, see LICENSE. An independent community plugin, not affiliated with the Omarchy project.