Omahub
← All plugins
D

Countdown

by Dorneles

Countdown to your special date. Simple and intuitive day counting menubar app with multi-event support, customizable formats, and clean design.

GitHub

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
1292b5e
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

None
AI risk level
None
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
1292b5e
Reviewed
1 month ago

This is a well-crafted, security-conscious countdown widget for the Omarchy desktop. The code is clean, readable, and demonstrates strong security practices including input sanitization, atomic file operations, symlink protection, and proper permission checks. No malicious behavior, hidden persistence, credential theft, or destructive operations were found.

  • The installer modifies ~/.config/omarchy/shell.json to register the widget, which is expected behavior for an Omarchy plugin but does modify a user config file (with atomic writes and safety checks).
  • The plugin installs a CLI tool to ~/.local/bin/countdown which could theoretically shadow another command, though 'countdown' is not a standard system command.
  • Config data is passed via command-line arguments to a Python helper, which is visible in process listings, but this is a negligible privacy concern for a single-user desktop.
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/jvlianodorneles/countdown --enable
Productivity #bar

⏳ Countdown

Countdown to your special date. Simple, intuitive day counting menubar app with multi-event management, customizable display formats, and seamless desktop integration for Omarchy and Quickshell. You will never miss the day!

License: MIT Omarchy Platform

Countdown Preview

✨ Features

  • Multi-Date Support: Register, edit, delete, and manage multiple countdowns and count-up events simultaneously.
  • Counting Down Days: Target date exclusive ($Days = \text{Target} - \text{Today}$). On the target date: D-Day / 0.
  • Counting Up Days: Target date inclusive ($Days = \text{Today} - \text{Target} + 1$). Perfect for tracking days since an anniversary, sobriety, or project launch.
  • Menubar Display: Unobtrusive, seamless status bar widget styled with your active Omarchy theme colors.
  • Prefix & Suffix Decorations: Decorate your countdowns with custom labels and emojis. Automatic spacing is handled seamlessly.
  • Built-in Searchable Emoji Picker: Integrated Unicode library with 1,870+ emojis and real-time keyword search directly inside the Prefix and Suffix fields.
  • Event Name Display: Displays the event name clearly on the status bar (e.g. ✈️ Vacation Trip: D-48 left).
  • Official Omarchy Panel: Interactive popup panel built with official design components (PanelHero, PanelSectionHeader, ButtonGroup, TextField).
  • Instant Format Cycling: Middle-click directly on the menubar widget to walk through all display formats.
  • Quick Event Cycling: Scroll the mouse wheel on the bar widget to cycle between your registered events.
  • Built-in CLI & IPC Control: Fast command line interface (countdown) for terminal automation and scripts.

🖥️ Display Methods

Format Name Option Key Examples
Numeric day numeric 100, 99, 0
D-day dday D-100 (countdown), D+100 (count-up), D-Day (today)
Short descriptive short_descriptive 2y 5mo 3d, 5mo 12d, 3d, Today
Long descriptive long_descriptive 2 years 5 months 3 days, 5 months 12 days, 3 days, Today

⌨️ Mouse & Keyboard Controls

Action Control Description
Toggle Panel Left-Click or Right-Click Opens the interactive event dashboard and editor
Cycle Format Middle-Click Walks through D-Day ➔ Numeric ➔ Short ➔ Long formats
Cycle Events Mouse Wheel Up / Down Steps through your registered events directly from the status bar
Dismiss Panel Escape or Click Outside Smoothly closes the popup panel

🚀 Installation

Run the automated installer script:

./install.sh

The installer will:

  1. Copy the plugin files to ~/.config/omarchy/plugins/dorneles.countdown.
  2. Install the countdown CLI tool to ~/.local/bin/countdown.
  3. Register the widget in your Omarchy shell.json configuration.
  4. Reload the shell.

To uninstall:

./uninstall.sh

🛠️ CLI Usage

The countdown CLI allows managing your dates directly from the terminal:

# List all registered events with live status
countdown list

# Add a future countdown (Exclusive)
countdown add --title "Trip to Tokyo" --date "2026-10-15" --prefix "✈️" --suffix "to go" --pin

# Add a past count-up tracker (Inclusive)
countdown add --title "No Smoking" --date "2026-01-01" --mode countup --prefix "🌱" --suffix "days strong"

# Pin an event to the status bar by ID
countdown pin evt_new_year

# Delete an event
countdown delete evt_100_days

# IPC triggers
countdown toggle
countdown refresh
countdown cycle-format
countdown cycle-event

🔒 Security Hardening

This plugin adheres to strict security and robustness standards:

  • PlainText UI Enforcement: All Text elements explicitly enforce textFormat: Text.PlainText to prevent RichText / HTML injection.
  • Control Character Stripping: All titles, prefixes, and suffixes are sanitized to strip non-printable ASCII and control characters (\x00-\x1f).
  • Input Length Caps: Enforces strict bounds (MAX_TITLE_LEN = 100, MAX_PREFIX_LEN = 30, MAX_EVENTS_COUNT = 50, MAX_CONFIG_SIZE = 64 KiB).
  • Atomic File Operations: State files are written atomically using temporary files and protected with 0o600 file permissions and 0o700 directory permissions.
  • Zero-IO File Watchers: Quickshell FileView watchers use blockAllReads: true to eliminate disk stalls on the UI thread.

🧪 Testing

Run the automated test suite:

node tests/model.test.js

📄 License

MIT © Juliano Dorneles dos Santos