Omahub
← All plugins
B

Screen Time

by Bivek Nepal

macOS-style screen time: per-app usage today, a 24-hour timeline, and a weekly view, tracked locally.

GitHub

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
8682240
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
8682240
Reviewed
1 month ago

The plugin is a local screen-time tracker with no network activity. It reads active window info and writes JSON state files under ~/.local/state, using careful file handling (O_NOFOLLOW, atomic writes, input sanitization) to mitigate symlink and injection risks. The code is well-structured and appears safe for its intended purpose.

  • The plugin reads window titles and app IDs, which could be considered sensitive, but this data stays local and is only used for the tracking display.
  • The Bash and Python helper scripts are invoked with fixed paths and no user-controlled arguments, reducing injection 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/bivekk51/TimeTrace --enable
System #system

Screen Time

A macOS-style Screen Time panel for the Omarchy Quattro bar: a glanceable total in the bar, and a detail panel with a 24-hour timeline and a ranked per-app breakdown — plus a seven-day overview. All tracking is local; nothing leaves your machine.

Features

  • Bar total — today's screen time (minutes-level, e.g. 1h 50m), updated on a slow cadence so it doesn't tick every second.
  • 24-hour timeline — a stacked bar of your day; each slot is colored by the app you were using, hover for the time and total.
  • Per-app breakdown — ranked by time, with category chips and proportional bars, colored per app (theme-aware, derived from the accent hue).
  • Week view — T toggles a seven-day bar chart and aggregated app totals.
  • Multi-browser — Firefox, Chrome, Chromium, Brave, LibreWolf, Zen, Vivaldi (and siblings) are tracked separately, and the active page is recovered from the window title so each browser doesn't collapse into one bucket.
  • Respects your time — idle time (configurable threshold) and the lock screen are excluded. No multi-monitor split; the focused window on the active seat is what counts.

Preview

The panel follows your Omarchy theme. Shown across a few:

Tokyo Night Solitude Matte Black
Tokyo Night Solitude Matte Black

Install

From this repo (or any git URL) into the Omarchy plugin directory:

omarchy plugin add https://github.com/bivekk51/screentime.git --enable --yes

Until published, you can drop the folder in manually:

cp -r bivekk51.screentime ~/.config/omarchy/plugins/
omarchy plugin enable bivekk51.screentime
omarchy bar move bivekk51.screentime --section right

Usage

  • Click the bar item to open/close the panel. Esc closes it.
  • T switches Today / Week. R forces a save.
  • Right-click or middle-click saves now.

Remove

omarchy plugin remove bivekk51.screentime

This only unloads the plugin and deletes its code under ~/.config/omarchy/plugins/. Your usage history is kept separately under ~/.local/state/bivekk51.screentime/ so removing and reinstalling doesn't lose data; delete that directory to wipe it completely:

rm -rf ~/.local/state/bivekk51.screentime

Configure

Settings live inline in ~/.config/omarchy/shell.json under the widget entry (omarchy bar set bivekk51.screentime <key> <value>):

Key Type Default Meaning
slotMinutes integer 30 Width of each 24h timeline segment (5–120).
idleThresholdSec integer 60 Stop counting after this much idle time.
excluded array [] App IDs (window classes) to ignore, e.g. ["steam"].

Data

Per-day usage is written as JSON under:

~/.local/state/bivekk51.screentime/YYYY-MM-DD.json

Writes are atomic (temp file + rename) and flushed periodically, on app change, and when the shell exits, so totals survive restarts. To reset, delete the day file(s).

Architecture

  • manifest.json — bar-widget plugin with inline settings (defaults/schema).
  • BarWidget.qml — bar label; loads the panel and forwards open/close/toggle.
  • Panel.qml — the detail view (hero total, timeline, app list, week view).
  • Service.qml — tracking engine: samples ToplevelManager.activeToplevel each second, accumulates into the active app, excluded idle/lock, and persists.
  • Tracker.js — pure helpers (formatting, slot math, stable per-app colors).
  • Categories.js — app-id → name/category/icon map, browser detection, and title→page parsing.
  • store.sh — atomic JSON writer (reads the payload from stdin).

UI chrome uses the Omarchy theme tokens (Style, Color) so it follows your theme; per-app segment colors are generated around the accent hue.

License

MIT — see LICENSE.