{"id":51292758,"url":"https://github.com/vtestah/zen-pomodoro","last_synced_at":"2026-06-30T12:00:43.654Z","repository":{"id":367624299,"uuid":"1281625817","full_name":"vtestah/zen-pomodoro","owner":"vtestah","description":"A calm, Zen-style Pomodoro focus timer applet for the Cinnamon desktop","archived":false,"fork":false,"pushed_at":"2026-06-26T20:17:18.000Z","size":3855,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-26T20:21:57.418Z","etag":null,"topics":["cinnamon","cinnamon-applet","cinnamon-spices","desktop-applet","focus-timer","gjs","javascript","linux","linux-mint","pomodoro","pomodoro-technique","pomodoro-timer","productivity","time-management"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vtestah.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-26T18:44:37.000Z","updated_at":"2026-06-26T20:17:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vtestah/zen-pomodoro","commit_stats":null,"previous_names":["vtestah/zen-pomodoro"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/vtestah/zen-pomodoro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vtestah%2Fzen-pomodoro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vtestah%2Fzen-pomodoro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vtestah%2Fzen-pomodoro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vtestah%2Fzen-pomodoro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vtestah","download_url":"https://codeload.github.com/vtestah/zen-pomodoro/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vtestah%2Fzen-pomodoro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34965643,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cinnamon","cinnamon-applet","cinnamon-spices","desktop-applet","focus-timer","gjs","javascript","linux","linux-mint","pomodoro","pomodoro-technique","pomodoro-timer","productivity","time-management"],"created_at":"2026-06-30T12:00:23.306Z","updated_at":"2026-06-30T12:00:43.642Z","avatar_url":"https://github.com/vtestah.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.svg\" width=\"128\" alt=\"Zen Pomodoro logo\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eZen Pomodoro\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eA calm, Zen-style Pomodoro timer for the Cinnamon panel.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/vtestah/zen-pomodoro/actions/workflows/tests.yml\"\u003e\u003cimg alt=\"tests\" src=\"https://img.shields.io/github/actions/workflow/status/vtestah/zen-pomodoro/tests.yml?branch=main\u0026style=flat-square\u0026logo=githubactions\u0026logoColor=white\u0026label=tests\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/vtestah/zen-pomodoro/releases\"\u003e\u003cimg alt=\"release\" src=\"https://img.shields.io/github/v/tag/vtestah/zen-pomodoro?style=flat-square\u0026logo=github\u0026logoColor=white\u0026label=release\u0026color=e35a3c\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"License: GPLv3\" src=\"https://img.shields.io/badge/license-GPLv3-blue.svg?style=flat-square\u0026logo=gnu\u0026logoColor=white\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"screenshot.png\" alt=\"Zen Pomodoro in action\" width=\"760\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"screenshot-stats.png\" alt=\"The Zen Pomodoro statistics dashboard\" width=\"760\"\u003e\n\u003c/p\u003e\n\nIt gives you gentle on-screen cues instead of anxious alarms: a soft glow frame\nthat traces your progress, a quiet start ritual, a calm ending, an optional\nfull-screen Zen mode, and a breathing guide on breaks.\n\n## Why Zen Pomodoro?\n\nMost Pomodoro timers interrupt you: a jarring alarm, a popup that demands a\nclick, a countdown that quietly piles on pressure. Zen Pomodoro takes the\nopposite approach. Your progress shows as a soft glow at the edge of the screen,\nfocus ends calmly instead of blinking at you, and if a block runs out while\nyou're mid-thought, **soft landing** waits for a natural pause instead of cutting\nyou off. It stays out of your way, works with a screen reader, and speaks 20\nlanguages.\n\nThis repository is the **single source of truth**, and the code in `6.4/` is the\npublic applet exactly as published. There is no personal/public split. Optional\n**site blocking** (edits a clearly-marked section of `/etc/hosts` via a\npolkit/pkexec prompt) and **Pushover** push notifications (you supply your own\nkeys) are regular, off-by-default features. `build-public.sh` simply packages\nthis source for Cinnamon Spices (see\n[Publishing to Cinnamon Spices](#publishing-to-cinnamon-spices)).\n\nOriginally based on **Pomodoro Timer** by *gfreeau* (GPLv3); since substantially rewritten.\n\n## Install\n\n**From Cinnamon (once published on Spices):** right-click the panel → *Applets*\n→ *Download* tab → search **\"Zen Pomodoro\"** → install, then enable it on the\n*Manage* tab.\n\n**Manual install (works today):**\n```bash\ngit clone https://github.com/vtestah/zen-pomodoro.git \\\n  ~/.local/share/cinnamon/applets/zen-pomodoro@vtestah\n```\nThe folder **must** be named `zen-pomodoro@vtestah` (the applet UUID); Cinnamon\nloads the matching version from `6.4/`. Then right-click the panel → *Applets* →\n*Manage* and enable **Zen Pomodoro**. To update later, `git pull` in that folder\nand reload the applet (or restart Cinnamon with `Ctrl+Alt+Esc`). Requires\nCinnamon 6.x; the applet keeps its data under `~/.local/state/zen-pomodoro/`.\n\n## Features\n- **Calm focus cues:** a soft edge-glow frame traces your progress (the panel\n  edge stays clear), with a calm ending (no last-minute blinking), a quiet start\n  ritual, an optional full-screen Zen spotlight, a breathing guide on breaks, and\n  a panel progress ring.\n- **Adaptive onboarding:** a short wizard tailors focus length, sounds, breaks\n  and blocking from a few questions, with a review step, keyboard and\n  screen-reader navigation, and a one-click \"Undo last setup\".\n- **Tasks:** a list with pomodoro estimates and per-task progress, a\n  focus-task picker, and quick *Current task* / *Task list* access from the menu.\n- **Statistics dashboard:** today, this week, this month, streak and all-time, an\n  hourly focus pattern, 14-day bars, a 12-week heatmap, a by-task breakdown,\n  milestones, a finish-time estimate, and one-click export to a CSV file.\n- **Goals \u0026 flow:** a daily goal with a streak and a local celebration,\n  flow-extend at the end of a pomodoro, **soft landing** (when a focus block ends\n  while you're still working, it waits for a natural pause instead of cutting you\n  off), idle auto-pause and resume, and an optional\n  **strict focus** mode with no pause or skip mid-block.\n- **Calmer breaks:** rotating rest tips with *+5 min* and *Skip break* right in\n  the notification, an optional breathing guide, an optional **lock screen on\n  breaks** (long breaks only, if you prefer), and **auto-pause and resume of\n  music and video** (MPRIS) while you step away.\n- **Stay focused:** optional **site blocking** (edits a clearly\n  marked block of `/etc/hosts` via a one-time polkit/pkexec authorization),\n  **Do-Not-Disturb** while focusing, and a global hotkey to **jot a distracting\n  thought** without leaving your flow.\n- **Sounds:** a ticking option, phase alerts, an interval chime, and ambient\n  soundscapes (white, pink or brown noise, rain, sea, or your own file).\n- **Push to your phone (optional):** phase changes via Pushover with your own\n  keys (stored as plain text in the applet's settings, like other applet\n  settings), and customizable message text, sound and priority.\n- **Automation (optional):** run a command of your choice when focus starts, a\n  break starts, or you reach your daily goal.\n- **Your look and controls:** theme presets and custom accent colours, frame\n  style (glow, border, corners or off), glow intensity, breathing pattern, menu\n  font scale and reduce-motion, all with a live preview; drive the timer from the\n  panel (scroll to start/pause or change focus length, middle-click to skip,\n  start-on-click) or with keyboard shortcuts.\n- **Resilient and accessible:** session recovery after a Cinnamon restart,\n  screen-reader summaries for the charts, and **localized into 20 languages**.\n\n## Layout\n- `6.4/`: the applet code for Cinnamon 6.x (`applet.js`, `menu.js`,\n  `features.js`, `visual.js`, `timer.js`, `sound.js`, `soundfx.js`, `dialogs.js`,\n  `constants.js`, `settings-schema.json`, `stylesheet.css`), plus the root-run\n  blocking helpers `hosts-helper.py` and `setup-passwordless.py`.\n- `po/`: translation sources (`.po`, `.pot`). Compiled `.mo` files go to\n  `~/.local/share/locale/...` and are **not** committed.\n- `metadata.json`: the single source of truth for the version.\n- `build-public.sh`: packages this source into the Spices layout under `dist/`.\n- `release.sh`, `cliff.toml`, `CHANGELOG.md`, `RELEASING.md`: release tooling.\n- `.githooks/commit-msg`: Conventional Commits check.\n- `*.svg`, `*.png`, `sounds/`: assets; `screenshot.png` is the Spices store image.\n\n## Development\nEdit here. It's the live applet, so reload to test:\n```\ndbus-send --session --dest=org.Cinnamon /org/Cinnamon \\\n  org.Cinnamon.ReloadXlet string:'zen-pomodoro@vtestah' string:'APPLET'\n```\n(or reload from Looking Glass). New translation strings only take effect after a\nfull Cinnamon restart, since `.mo` files are cached per process.\n\nCommits follow [Conventional Commits], enforced by a dependency-free hook.\nEnable it once per clone:\n```\ngit config core.hooksPath .githooks\n```\n\nBack up to your own remote:\n```\ngit remote add origin git@github.com:vtestah/zen-pomodoro.git\ngit push -u origin main\n```\n\n## Releasing\n`metadata.json` is the only place the version lives. `./release.sh` computes the\nnext version from your commits (via [git-cliff]), bumps `metadata.json`,\nregenerates `CHANGELOG.md`, makes a `chore(release): vX.Y.Z` commit and tag, and\noffers to build the public package. Full steps in **[RELEASING.md](RELEASING.md)**.\n\n## Translations\nEight of the 20 catalogs are fully translated (`ru`, `de`, `es`, `fr`, `it`, `nl`, `pt`, `pt_BR`); the rest are partial and fall back to English for untranslated strings. To pick up new strings:\nregenerate the `.pot` (`cinnamon-xlet-makepot` run from `6.4/`), `msgmerge` the\n`.po` files, fill the gaps, and `msgfmt --check`. `ru` is hand-maintained; the\nremaining catalogs are machine translations; native review welcome.\n\n## Publishing to Cinnamon Spices\n`./build-public.sh` packages this source into `dist/zen-pomodoro@vtestah/`: it\nlays the package out as `UUID/files/UUID/`, writes a clean `metadata.json` (no\n`last-edited` / `icon` / `dangerous`), ships only `.po` (no compiled `.mo`), and\nincludes the blocking helpers. A validator fails the build if a personal path,\n`sudo`, a leftover `@PUBLIC_STRIP` marker, or the removed custom-scripts feature\never reappears.\n\nThat export goes into a fork of `linuxmint/cinnamon-spices-applets` as a PR\ntitled `Zen Pomodoro vX.Y.Z: \u003csummary\u003e` (their convention; PRs are squash-merged).\n\n## Credits \u0026 License\nOriginally based on **Pomodoro Timer** by *gfreeau*, since substantially rewritten. Licensed under the **GPLv3** (see [LICENSE](LICENSE)).\n\n[Conventional Commits]: https://www.conventionalcommits.org\n[git-cliff]: https://git-cliff.org\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvtestah%2Fzen-pomodoro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvtestah%2Fzen-pomodoro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvtestah%2Fzen-pomodoro/lists"}