Omarchy Pomodoro

A Pomodoro timer for the Omarchy bar, running inside omarchy-shell (Quickshell). Focus/break sessions, a live bar countdown, today/week/month stats, and three reminder styles.

Features

• Customizable focus and break durations (1–180 minutes).
• Start focus / start break / pause / resume / reset.
• Live countdown on the bar, e.g. 🍅 24:32; break shows ☕, idle shows today's count 🍅 3.
• Each completed focus records a 🍅.
• Stats for today, this week (ISO week), and this month.
• Three reminder modes when a session ends: system notification, fullscreen overlay, or lock screen.
• Settings and stats survive plugin reloads and shell restarts.

Requirements

• Omarchy (the plugin runs inside omarchy-shell).

No external dependencies — it uses only Quickshell and the Omarchy UI kit (qs.Commons), which ship with Omarchy itself.

Install

omarchy plugin add https://github.com/GengCen-Qin/omarchy-pomodoro.git --enable --yes

This clones the repo into ~/.config/omarchy/plugins/lucas.pomodoro/ (named by the manifest id), validates it, and enables the plugin. The bar widget appears immediately; move it later with omarchy bar move lucas.pomodoro --section right.

--enable turns it on right away. Omit it (and --yes) to install disabled and review the code first, then run omarchy plugin enable lucas.pomodoro.

To update to the latest version later:

omarchy plugin update lucas.pomodoro

The plugin id is lucas.pomodoro. To use a different id, rename the directory and update id in manifest.json, plus every moduleName, ipcTarget, and serviceFor("lucas.pomodoro") reference in Service.qml, BarWidget.qml, and Panel.qml.

Uninstall

omarchy plugin remove lucas.pomodoro

This removes the plugin from the bar and deletes the checkout. Settings and stats are stored in ~/.local/state/omarchy/pomodoro.json; delete that file too to wipe all data.

To keep the files but stop it running, use omarchy plugin disable lucas.pomodoro.

Usage

Panel

Left-click opens the panel, which shows the current countdown and lets you:

• Start focus, start break, pause/resume, reset.
• Adjust focus and break durations with the − / + steppers.
• Toggle auto-start of the next phase (break after focus, focus after break).
• Pick the reminder mode: Notify (desktop notification), Overlay (fullscreen page), or Lock (lock screen).
• View today / week / month pomodoro counts.

Keyboard

With the panel focused: s start focus, p pause/resume, r reset, Esc close.

IPC

Drive the timer from scripts or keybindings:

omarchy-shell pomodoro status
omarchy-shell pomodoro startFocus
omarchy-shell pomodoro startBreak
omarchy-shell pomodoro pause
omarchy-shell pomodoro resume
omarchy-shell pomodoro reset

status returns JSON, e.g.

{
  "phase": "focus",
  "running": true,
  "remaining": 1499175,
  "total": 1500000,
  "focusMinutes": 25,
  "breakMinutes": 5,
  "autoStartBreak": true,
  "autoStartFocus": false,
  "reminderMode": "notification",
  "overlay": false,
  "today": 3,
  "week": 7,
  "month": 22
}

Data

Settings and stats are stored in ~/.local/state/omarchy/pomodoro.json. Delete that file to reset everything.

Files

• Service.qml — singleton timer engine, stats, persistence, reminders, IPC.
• BarWidget.qml — bar label and panel host.
• Panel.qml — the control panel popup.
• Model.js — pure logic (time formatting, ISO week, stat bucketing).
• StepperRow.qml — − value + control for durations.

Maintainer notes

• Install — nothing special: omarchy plugin add <repo-url> --enable works out of the box; the plugin is a plain git checkout.
• Permissions — runs unsandboxed inside omarchy-shell like every plugin; it never runs shell commands, never touches the network, and never modifies user config. The only file it writes is its own state file ~/.local/state/omarchy/pomodoro.json.
• Dependencies — none beyond Omarchy itself (Quickshell + qs.Commons).

License

MIT