Gentle Pomodoro

A visually soothing, task-integrated Pomodoro timer for your daily focus work. Four ambient themes — Classic (day→night gradient), Frosted Glass (drifting colour orbs behind a frosted pane), Frosted Glass 2 (the same idea drawn as real glass, with a lit rim) or Pixel City (a pixel-art city whose windows light up as night falls) — instead of a ticking clock, task linking with the Tasks plugin, and Dataview-friendly daily logs.

v0.6.8 (beta). Available in the Obsidian Community Plugins catalog. See Install.

Features

🍅 Gentle visual timer

• Four themes: Classic (the original day → dusk → night gradient), Frosted Glass (three drifting colour orbs behind a 3D frosted pane — pastel-twilight palette in light mode, fireplace warmth in dark mode), Frosted Glass 2 (the same idea drawn as real glass: a thin lit rim that picks up the session's colour, two highlights on the edge, sharper colour balls behind the pane, and an edge shade that follows your own theme's background colour so it sits well on light and coloured themes) and Pixel City (a pixel-art city under a dithered sky; the windows come on wave by wave as the session runs toward night, and go dark again over a break). Switch in the main Obsidian Settings tab.
• Ambient shape that transitions through warm → cool colors as the timer runs.
• Configurable focus / short break / long break durations. Classic Pomodoro: long break every 4 focus sessions (configurable).
• Overtime tracking — the timer counts up with a subtle glow after the session ends.
• Estimated end time — while a session runs, the timer shows the wall-clock time you'll finish (e.g. Ends 15:30, with (+1 day) if it crosses midnight): a calm way to know when you're free without watching the countdown. Toggle in settings.
• Optional audio cues (war drum on start, bell/ding on finish) — bundled into the plugin, no extra downloads needed. Choose the end sounds yourself: any of the three built-ins, or your own mp3, m4a or wav file from the vault (up to 30 seconds).
• Notify when time is up (computers, opt-in) — a silent system notification when focus or break time is up, so you notice even when other windows cover Obsidian. It works with the timer's sounds off. Turning it on shows a sample, which is when your computer may ask to allow notifications from Obsidian.
• Respects prefers-reduced-motion: timer animations soften when the OS requests it.

✅ Task integration

• Pick tasks straight from your vault. Compatible with the Tasks format: - [ ] Task ⏳ 2025-12-23 🆔 abc123 — on any list bullet (-, *, +, or numbered).
• Choose where tasks come from: a tasks folder, the note you are in, or every note you have open. The two note options also show tasks with no date, under a No date heading — handy if you keep todos inline in your notes rather than in one folder.
• Smart filtering: Overdue, Today, Tomorrow, and upcoming tasks. Choose the lookahead window (3 / 5 / 7 / 14 / 30 days) in settings; overdue tasks always show.
• Your linked task stays linked when you change where tasks come from — if the new scope would not show it, it appears at the top under Linked task. Only ticking it off unlinks it.
• The Current task button shows the task's name without its tags, on up to two lines; on a computer, hover it to read a longer name in full.
• One-click Unlink current task.
• Opt-in (beta — edits your task files): adds a lifetime 🍅 N count to the task line each time you finish a focus session for it, placed before the Tasks date fields so they keep parsing (e.g. - [ ] Write docs 🍅 3 ⏳ 2025-12-23).
• Recovery actions (settings buttons + commands): if an older version left markers after your task dates and broke their parsing — Check counts them without changing anything, Repair moves them back in place, Remove deletes the misplaced ones, and Remove all deletes every marker the counter ever wrote (back up your vault first). The writing actions ask for confirmation with exact counts first. Repair and Remove only act on a marker sitting after a task's date fields — the placement that breaks them, whoever typed it — and Remove all leaves alone a 🍅 N you typed inside a task's own text (one at the very end of the line counts as a marker).

📊 Daily focus goal

• Set a daily focus target (default 2h, set to 0 to disable).
• The status bar shows progress as a thin ring that fills toward the goal and changes when the goal is met. Hover for Today: 1h 12m of 2h 0m, or turn on the text in settings.
• One-time "goal hit" notice each day. Resets automatically at local midnight.

📝 Dataview-friendly daily logs

• One markdown file per day: <folder>/YYYY-MM-DD-gentle-pomodoro-log.md.
• One inline-field line per session (start, end, pauses, duration, status, type).
• Rename-safe when tasks carry 🆔 — past log lines update on rename, or via the Refresh log task names by ID command.

🧭 Status bar

• A small mark shows at a glance whether the timer is idle, running, paused, or its time is up — the end of a session is silent by design, so a glance at the corner is the gentle way to know. Beside it: Focus, Break or Long break.
• A thin ring around the mark fills toward today's focus goal.
• Click it (or right-click) for a menu: Start / Pause / Resume, Finish & next, Skip to next, Open timer, and which time to show.
• Time: hidden by default, like the timer panel's countdown. Or show minutes left (12m), a clock (12:34), or the end time (Ends 15:30).
• Hover for everything else: time left and end time, the linked task, and today's focus against your goal.
• Computers only — Obsidian has no status bar on phones and tablets.

🎵 Lofi study music

• Paste a YouTube link — video, 24/7 live stream (Lofi Girl!), or playlist — and a ▶️ play/pause/stop row appears in the panel. Audio-only by design: no video is ever shown.
• Up to three links, each with an optional short name. A line above the controls says what's playing; the list button opens the picker.
• ⏭ next link carries the audio across the switch. Picking one from the list doesn't — press ▶️ to start it.
• ⏪ / ⏩ move through a playlist, on their own row that appears only when the link is genuinely a playlist.
• Links check and name themselves: paste one and a bad link says so, while the name box fills in from the title. Type over it any time.
• Fades in and out on every control — ▶️, ⏸, ⏹ and track skips all ease rather than cut. Change your mind mid-fade and it carries on.
• Gentle ducking: session cues briefly dip the music and ease it back up, so they stay audible without jolting the mix.
• Loops by default (turn off Loop music to play once), with a Music sound mute and a Low / Mid / High music volume in the in-view settings. The mute silences without stopping, so a live stream stays live.
• Resumes where you left off, per link. ⏹ Stop — or changing that link — makes it start from the top instead. Live streams always start live.
• Fully manual — independent of your sessions; stops when you close the panel. A notice tells you if playback stalls.
• Desktop only. YouTube won't load its player inside Obsidian on iOS at all (error 153) — no link works there, and nothing the plugin can set changes it. Every other feature works on mobile.

📱 Mobile (iPad & phone)

• Touch-friendly: bigger tap targets, one smooth-scrolling panel, and a layout that adapts to the screen — on a short/landscape phone the timer shrinks and gets out of the way.
• Tap the timer shape to peek at the hidden countdown — it fades back on its own after a couple of seconds. The daily-goal progress shows in the view (Obsidian hides the status bar on mobile).
• Sound: press Start once to unlock audio, and note iOS's hardware silent switch mutes it — platform constraints, not bugs.
• Notify when time is up is for computers only — the mobile apps can't show system notifications, so the switch isn't shown there.
• Lofi music doesn't play on iPhone or iPad — YouTube won't load its player inside Obsidian there (error 153). See Lofi study music for why; it isn't the link, and no other link works.

Install

Community Plugins (recommended)

1. Open Settings → Community plugins → Browse.
2. Search for Gentle Pomodoro and click Install.
3. Enable it in Community plugins.

Or grab it directly from the Obsidian catalog page.

Manual

1. Download main.js, manifest.json, and styles.css from the latest release. Audio is bundled into main.js — no extra files needed.
2. Drop them into <vault>/.obsidian/plugins/gentle-pomo/.
3. Reload and enable in Community Plugins.

Configure

Settings tab (Settings → Gentle Pomodoro), grouped into sections (findable via Obsidian's settings search on Obsidian 1.13+):

• Display & behavior: log folder path and auto-open on startup.
• Status bar (computers only): show in status bar, time in status bar (hidden, minutes left, clock or end time — also in the status bar's own menu), and show today's total as text beside the goal ring.
• Timer appearance: theme (Classic default, Frosted glass, Frosted glass 2 or Pixel city), show day/night indicator, and estimated end time (shown while a session runs).
• Audio: timer sounds (the master switch — it also covers the start drum and the Stop sound, and never touches the music) and the music sound mute. Both also live in the timer panel, and the two surfaces follow each other; the volumes are in the timer panel only, since a level is something you move while listening.
• When focus ends and When a break ends — the same headings as the timer panel. Each group has:
  • Focus-end sound / Break-end sound — the singing bell and the ding by default. Pick another built-in sound or your own mp3, m4a or wav file from the vault (up to 30 seconds); picking plays it once, and ▶ plays it again — while a sound plays, ▶ turns into ■ to stop it. Only one plays at a time: picking another sound, pressing the other row's ▶, switching Timer sounds off or closing the settings stops it. A file that can't be used is refused when you pick it, with the reason. If a chosen file goes missing on a device (not synced yet, deleted, renamed), the built-in sound plays and the row says why. The sound always plays when you stop or skip that session. Settings tab only.
  • Play it when focus time is up / Play it when break time is up — rings the sound once when that session's time is up, whether the timer runs into overtime or starts the next session.
  • Auto-start the break / Auto-start focus.
  • A line saying what will actually happen with the settings you have.
  • Using your own sound: first put the file in your vault — drag it into Obsidian's file list, or on a phone attach it to any note — then pick it from the list. Files in hidden folders such as .obsidian aren't listed. On your other devices it plays once the file has synced there (with Obsidian Sync, only while its Sync audio option is on — it is by default); until then the built-in sound plays.
• Notifications (computers only): notify when time is up — a silent system notification when focus or break time is up. Also in the timer panel.
• Music: music link 1–3 (video, live stream, or playlist — audio-only playback in the timer panel), each with an optional name shown in the panel and filled in for you when you paste a link, show music player (turning it off also stops playback), loop music (replay from the start when it ends; on by default), and resume where you left off (reopen each link at the moment you paused; on by default).
• Long break: duration (default 15m) and focus sessions before a long break (default 4).
• Daily focus goal: minutes (default 120, 0 turns it off) and show a notice when you reach the goal.
• Task picker: where to find tasks (tasks folder / current note / open notes); tasks folder path; show task picker (defaults to hidden until you set a tasks folder path; turning it off unlinks the current task); task lookahead window — how many days ahead the picker reaches (3 / 5 / 7 / 14 / 30 days; default 3), with overdue tasks always shown.
• Task integration: count pomodoros on the task (opt-in, beta — edits your task files), plus the marker recovery actions: check / repair / remove misplaced / remove all.

In-view panel (gear icon on the timer) — grouped into sections:

• Timing: focus and break durations (press Enter to apply). The long break is set in the settings tab.
• Tasks: Where to find tasks — tasks folder / current note / open notes. Hidden while Show task picker is off.
• Audio: Timer sounds with Timer volume, and Music sound with Music volume — two matched pairs. The two switches also appear in the settings tab's Audio group; the volumes live here only. The music pair is hidden while Show music player is off.
• When focus ends / When a break ends: each holds that moment's Play a sound and its Auto-start toggle, plus a line saying what will actually happen. The buttons stay explicit: Stop (finish & next) always switches to the next session paused, while Skip starts it (when auto-start is on).
• Notifications (computers only): Notify when time is up — the same switch as in the settings tab.
• End-of-session sounds: by default a session that runs out stays silent and the timer counts up — deliberately, so a chime never interrupts focus you want to keep going with. Turn on Play a sound under When a break ends or When focus ends to be told anyway (in the settings tab: Play it when break time is up / Play it when focus time is up). A new install starts with the break sound on and the focus one off; upgrading keeps whatever you hear today. Each applies whether the timer runs into overtime or auto-starts the next session, so auto-start can be silent too. Both sit in the timer panel and in the settings tab, and follow the master Timer sounds switch. Which sound plays is chosen in the settings tab, at the top of the same group.
• Full-width Reset to defaults button at the bottom.

Layout adapts to narrow sidebars: the timer visual stays sticky at the top, controls keep a comfortable minimum width and the panel scrolls horizontally if needed.

Log format

Each session appends one line to the day's log file:

- 🍅 Focus | Task:: [[Projects/Docs.md|Write docs]] | ID:: abcd12 | Start:: 2025-12-23 10:00:00 | End:: 2025-12-23 10:25:00 | Scheduled:: 1500 | Pauses:: [] | Total:: 1500 | Status:: finished | Type:: focus
- ☕ Rest | Start:: 2025-12-23 10:25:00 | End:: 2025-12-23 10:30:00 | Scheduled:: 300 | Total:: 300 | Type:: short-break
- ☕ Rest | Start:: 2025-12-23 11:00:00 | End:: 2025-12-23 11:15:00 | Scheduled:: 900 | Total:: 900 | Type:: long-break

Type:: is focus | short-break | long-break. Field order is stable — safe to pin Dataview queries against it.

Commands

• Open view
• Start / Pause / Finish & next / Skip to next
• Refresh log task names by ID
• Show in status bar / Hide from status bar
• Check for misplaced pomodoro count markers / Repair misplaced pomodoro count markers / Remove misplaced pomodoro count markers / Remove all pomodoro count markers

Compatible plugins

• Tasks — the task picker reads its emoji-marker format.
• Dataview — daily log lines use inline fields, ready to query.

Files the plugin reads

What the plugin reads and writes in your vault, and when:

• Task picker — when you open it, reads the notes that Where to find tasks points at: the tasks folder and its subfolders (or the whole vault if that field is empty), the current note, or your open notes; plus the note that holds your linked task.
• Linked task — reads that task's note to keep its name up to date and to unlink it when you tick it off; with the opt-in 🍅 counter on, edits only that task's line.
• Daily logs — writes one log file a day in your log folder and reads today's for the daily goal; renaming a linked task, or the Refresh log task names by ID command, rewrites task names inside the logs in that folder.
• Sound picker — lists the vault's mp3, m4a and wav files when you open it, and reads only the file you pick.
• 🍅 Check / Repair / Remove — scan every note, only when you press them.

Nothing here leaves your device. The only network use is YouTube, described below.

Network use

Timers, logs, and sounds are all local (audio cues are bundled into main.js, or read from your own vault if you choose a file). The optional lofi-music feature is the only part that reaches the network, in two places — both only ever to YouTube, and neither happens until you paste a music link.

Playing the audio. With a music link set and Show music player on, the timer panel embeds YouTube's privacy-enhanced player from www.youtube-nocookie.com to stream the audio, which loads content from YouTube/Google servers. This happens only while the timer panel is open; clearing the link or turning the toggle off stops it entirely.

Checking a link. When you paste or edit a link in the settings, the plugin makes one small request to www.youtube-nocookie.com/oembed about that link, to tell you if YouTube can't find it and to offer a name for it. It is sent shortly after you stop typing, and it carries only the video or playlist ID you pasted. Unlike the player above, this happens even with the timer panel closed and Show music player off — those control playback, not the settings page. No request is made for an empty slot, and a link YouTube confirms is remembered for the session, so editing the same working link twice doesn't ask twice. A link it can't find is re-checked at most once a minute, in case it was only just published.

YouTube's handling of both is covered by Google's privacy policy.

Issues & feedback

Found a bug or have an idea? Please open an issue on the GitHub issue tracker — bug reports and feature requests are welcome.

Development

npm install
npm run dev          # rollup --watch (rebuilds main.js)
npm run build        # one-shot production build
npm test             # vitest
npm run lint
npm run format       # prettier --write .

CI on every push runs lint, format-check, tests, and build. Release tags push a GitHub Release with main.js, manifest.json, and styles.css attached.

Credits

• Ding sound — Universfield via Pixabay.
• Bell sounds — freesound_community via Pixabay.
• War drum — freesound_community via Pixabay.
• Pixel City artwork — drawn by this repository's own script (art/pixel-city/), MIT like the rest of the plugin. Palette: Endesga 32 by Endesga.

AI disclaimer

Parts of this plugin were developed with AI assistance (Codex, Gemini, Claude). All code reviewed and tested by the maintainer before release.

License

MIT