jamiestudio-lab3k downloadsA visually soothing, task-integrated Pomodoro timer. Focus on your work with gentle animations and Pomodoro logging.

A calm Pomodoro timer for Obsidian. Instead of a ticking clock, a picture changes slowly from day to night as you focus. Link a session to a task from the Tasks plugin, and keep a daily log you can read with Dataview.
v0.7.2 (beta). In the Obsidian Community Plugins catalog. See Install.
Ends 15:30.- [ ] Write docs ⏳ 2025-12-23 🆔 abc123, on any bullet (-, *, + or numbered).🍅 N count on the task's line, placed before the Tasks fields so its dates keep working: - [ ] Write docs 🍅 3 ⏳ 2025-12-23. A 🍅 you typed in the task's own text is left alone.🍅 N after a task's dates, whoever typed it, and Remove all also on one at the end of a task's text. Cancelled and in-progress tasks are included. The tools that write ask first, with exact counts.Today 1h 12m / 2h 0m.<folder>/YYYY-MM-DD-gentle-pomodoro-log.md, with a line per session. Choose the folder under Settings → Daily log. With no folder set, nothing is logged.🆔, its past lines take the new name. Refresh log task names by ID catches up on renames made while the task wasn't linked.Needs Obsidian 1.7.2 or later.
Or open the catalog page.
main.js, manifest.json and styles.css from the latest release. The sounds and images are inside main.js.<vault>/.obsidian/plugins/gentle-pomo/.On Obsidian 1.13 and later, the settings open on a list of pages, each showing its current value. Obsidian's settings search finds any setting inside them. On older versions, the same settings are on one page, in the same order.
| Page | What's on it |
|---|---|
| Timer | Auto-open on startup; theme, day/night indicator and estimated end time; long break length (15 min) and focus sessions before a long break (4); daily focus goal (120 min) and its notice. |
| Status bar (computers) | Show in status bar, which time it shows, and today's total as text. |
| Sounds and notifications (Sounds on phones and tablets) | Timer sounds and Music sound, to mute either. For the end of focus and of a break: which sound, whether it plays when time is up, whether the next session starts by itself, and a line saying what will happen. Notifications. |
| Music | Three links and their names, show music player, loop, resume where you left off. |
| Daily log | Log folder, day starts at, task switch, ask about long sessions, this device's name. Buttons: Open today's log, Check log, Convert old log lines, Refresh task names, Export sessions. |
| Focus note | Offer a focus note, Show “Last time” under the task, and a button that opens the card for the last session. |
| Log tables | See Log tables. |
| Tasks | Where to find tasks, tasks folder, show task picker, how many days ahead; the 🍅 count and its tools. |
A warning sign on Music means a link that isn't a YouTube link. On Daily log, it means a folder the log's tools can't use, such as the vault's top level. On Focus note, it means the note is on but no log folder is set, so notes have nowhere to go.
Good to know:
Device, to tell your devices apart. See Privacy.Focus and break lengths (press Enter to apply; a session under way keeps its length), where to find tasks, Timer sounds and Music sound with their volumes, and for the end of focus and of a break a sound switch and auto-start, plus Offer a focus note after focus. On computers, also notifications. Reset to defaults at the bottom resets these.
The focus and break lengths and the volumes are only here. The switches are in the settings too, and the two stay in step.
Each session adds a line to the day's log file (a line per task with Split at the switch; none for a session under a minute):
- 🍅 Focus [Task:: [[Projects/Docs.md|Write docs]]] [ID:: abcd12] [Start:: 2026-10-02 10:00:00] [End:: 2026-10-02 10:25:00] [Scheduled:: 1500] [Pauses:: []] [Total:: 1500] [Status:: finished] [Type:: focus] [Overtime:: 0] [Session:: s7k2m9qx4w] [StartedBy:: start] [EndedBy:: time-up] [Planned:: 1500] [Cycle:: 2] [Offset:: -300]
- ☕ Rest [Start:: 2026-10-02 10:25:00] [End:: 2026-10-02 10:30:00] [Scheduled:: 300] [Total:: 300] [Type:: short-break] [Session:: s3d9w6hq2e] [StartedBy:: auto] [EndedBy:: stop] [Planned:: 300] [Offset:: -300]
- ☕ Rest [Start:: 2026-10-02 11:00:00] [End:: 2026-10-02 11:15:00] [Scheduled:: 900] [Total:: 900] [Type:: long-break] [Session:: s5h2x8kv0b] [StartedBy:: auto] [EndedBy:: time-up] [Planned:: 900] [Offset:: -300]
| Field | What it holds |
|---|---|
Task |
Focus only. A link to the task's note, shown with the task's name and tags; just the name when the task has no note; No Task when none was linked. |
ID |
Focus only, when the task has a 🆔. |
Start, End |
Local time, YYYY-MM-DD HH:mm:ss, always with the digits 0–9. |
Scheduled |
The session length in your settings when it started, in seconds. |
Pauses |
Focus only. A list of "start - end" pauses. |
Total |
Active seconds: End − Start − the pauses. |
Status |
Focus only. finished (Stop, or time up) or cancelled (Skip). Skipped focus doesn't count toward the goal. |
Type |
focus, short-break or long-break. |
Overtime |
Focus only. Active seconds past the planned end; 0 when it ended on time or early. |
Rest lines have no Pauses or Status.
Added in 0.7.0, at the end of each line the timer writes. Some only when they apply:
| Field | What it holds |
|---|---|
Session |
An ID for the session, like s7k2m9qx4w. The lines of a session split at a task switch share it. |
StartedBy |
start (you pressed Start), auto (it began by itself), reset (after Reset) or added (Add a session). |
EndedBy |
time-up (time ran out and the next session started by itself), stop, planned-end (Stop's End at planned end), skip, recovered, recovered-planned-end (logged at the next start) or added. |
Planned |
The timer's planned length when it ended, in seconds, including any +5 or −5. |
Cycle |
Focus only: 1 up to Focus sessions before a long break. Not on a skipped, recovered or added focus. |
Offset |
Minutes east of UTC when it began: -300 is UTC−5. |
OffsetChange |
Minutes the clocks moved during the session. Only when a clock change happened. |
Slept |
Computers only. About how many seconds the timer was paused for a sleep of over 10 minutes (an estimate). Only when it paused for one. |
Dropped |
Seconds left out when a session was ended at its planned end. Only when above 0. |
Device |
This device's name, when you've set one. |
Session is older: from before 0.7.0, converted, or written by a device still on 0.6.9. The new fields are unknown on it, not 0, and nothing adds them later.Note (0.7.1, below) is not written with the line. It is added afterwards, and only if you save a focus note.added for how it began and ended. It has no Cycle, Slept, Dropped or Device.Slept, Dropped or Cycle when the change makes them untrue.Added in 0.7.1, after Device, only if you save a focus note:
| Field | What it holds |
|---|---|
Note |
The focus note: frown, meh or smile, then ·, then your words. Either part can be left out: smile, meh · stuck on refs, stuck on refs. |
With Offer a focus note on (Settings → Focus note), saving the card adds [Note:: …] to the end of that session's line, written after the session:
- 🍅 Focus [Task:: …] … [Device:: Laptop] [Note:: meh · stuck on the second paragraph]
Session, and on the last line of a session split at a task switch. A break never has one. Words alone that read like a face (meh, smile · fine) are saved as that face.[[link]] keeps only the text it shows, other [ and ] become ( and ), :: becomes :, line breaks become /, # becomes a look-alike # (so it isn't a tag), %% becomes %, 🍅 and ☕ are dropped, and it is cut to 500 characters. The box shows what was kept. Other marks, such as *, stay and show as Markdown in the log note.Note has no note. Nothing is filled in for older lines.7 is a number, 2026-11-03 a date, 45 min a duration, true a yes/no, and 1, 2 a list, and "quoted" loses its quotes; a note that is just null stays the word. The Log tables column shows each as Dataview prints it. The read API and Export give the words as written.Offset shows your time zone, and Device names a machine. A focus note is in your log in plain text. If you publish your log folder, they go with it. Leave This device's name empty to write no Device.
Today's log file starts with the day's goal, in minutes:
---
goal_minutes: 120
---
The timer keeps it up to date during the day. A past day keeps the goal it ended with. With the goal off, it's taken out. Your own properties in the file are kept.
Field names and their order are stable, so queries can rely on them; new fields are only added at the end. Dataview reads Start and End as text; use date(s.Start, "yyyy-MM-dd HH:mm:ss") for a date. Two examples — put your log folder in place of Your log folder, or use the Copy buttons under Log tables, which fill it in:
```dataview
TABLE WITHOUT ID s.Task AS Task, s.Start AS Start, round(s.Total / 60) AS Minutes, s.Status AS Status
FROM "Your log folder"
FLATTEN file.lists AS s
WHERE file.day AND endswith(file.name, "-gentle-pomodoro-log") AND (s.Type = "focus" OR (s.Type = null AND s.Start != null AND s.Total != null AND startswith(s.text, "🍅 Focus [")))
SORT s.Start DESC
LIMIT 20
```
```dataview
TABLE WITHOUT ID key AS Day, round(sum(rows.s.Total) / 60) AS "Focus minutes"
FROM "Your log folder"
FLATTEN file.lists AS s
WHERE file.day AND endswith(file.name, "-gentle-pomodoro-log") AND (s.Type = "focus" OR (s.Type = null AND s.Start != null AND s.Total != null AND startswith(s.text, "🍅 Focus ["))) AND s.Status != "cancelled"
GROUP BY file.day
SORT key DESC
```
The first lists your latest focus sessions. The second adds up each day's focus as the daily goal does, once old lines are converted. Tips for writing your own:
file.day AND endswith(file.name, "-gentle-pomodoro-log"), so other notes in the folder aren't counted.s.Type = null … part takes in focus lines from logs older than the Type field.s.Total, not s.total.choice(s.Planned != null, round(default(s.Planned, 0) / 60), null) rather than round(s.Planned / 60).Note after Device, on a focus line whose note you saved. A pattern anchored on Device being last, like \[Device:: [^\]]*\]$, stops matching that line; read the field by name instead.Overtime is no longer the last field. A pattern anchored on the end, like \[Overtime:: \d+\]$, stops matching; read the field by name instead (Overtime::\s*(\d+)). Update every device that logs: a device still on 0.6.9 writes lines without the new fields.- 🍅 Focus | Task:: … | Total:: 1500 | …, and Dataview couldn't read them. A pattern for a number or a word, like Total::\s*(\d+), reads both. One that ends a value at | or the end of the line must now also stop at ]. A script that splits a line on | reads only old lines. Old lines stay as they are until you run Convert old log lines, which adds no Overtime: a converted line has none (unknown, not 0).Settings → Log tables gives you a table of your sessions to paste into any note. The Copy buttons copy ordinary Dataview code with your log folder filled in. Dataview draws it, and you can change it as you like.
A copy is a snapshot: change the settings and copy again. Older lines show - for fields they don't have. With no log folder set there's nothing to copy, and a notice says so. If the clipboard is blocked, the code opens in a window to copy by hand.
Settings → Daily log → Export sessions, or the command Export sessions, saves your sessions to a new file for a spreadsheet or a script. Choose:
YYYY-MM-DD).Pomodoro exports by default. The dialog tells you if a folder can't be used, such as the vault's top level, a hidden folder, or a name some systems refuse.Your last format and folder are remembered. The file is named like gentle-pomodoro-sessions-2026-09-23-to-2026-10-22-091500.csv. Each export makes a new file (adding 2, 3… if the name is taken), never overwrites a file it can see (one a sync drops there at that very moment can be replaced), and never changes your log. It reads the file back and warns you if a sync changed it.
date, kind, type, start, end, startIso, endIso, task, taskPath, id, scheduled, planned, total, overtime, pauseCount, pausedSeconds, status, sessionId, startedBy, endedBy, cycle, offset, endOffset, slept, dropped, device, logFile, face, note. New columns are only added at the end.task is { name, path } in place of task and taskPath, and pauses is a list of { start, end } in place of pauseCount and pausedSeconds.date is the log's day, as Day starts at counts it. startIso and endIso add the time zone.null in JSON) means the line doesn't have that value, as on older lines.=, +, -, @, a tab or a carriage return) gets a ' in front, so a spreadsheet doesn't run it.To see the file in Obsidian, turn on Show all file types (Settings → Files and links). To sync it with Obsidian Sync, turn on Sync all other types.
For dataviewjs reviews, the plugin offers a small read-only API, so you don't need your own parser:
```dataviewjs
const pomo = app.plugins.plugins["gentle-pomo"]?.api;
const date = dv.current().file.day?.toFormat("yyyy-MM-dd");
if (pomo && date) {
const day = await pomo.getDay(date);
// Days logged before 0.6.9 have no goal of their own: fall back to this note's.
const goal = day.goalMinutes ?? (dv.current().focusgoalhours ?? 2) * 60;
dv.paragraph(`Focus: ${Math.round(day.focusSeconds / 60)} of ${goal} minutes`);
dv.table(
["Start", "Task", "Minutes", "Status"],
day.sessions
.filter((s) => s.kind === "focus")
.map((s) => [s.start, s.task?.name ?? "", Math.round((s.total ?? 0) / 60), s.status])
);
}
```
| Member | What it gives |
|---|---|
version |
1. |
dailyGoalMinutes() |
The daily goal setting in minutes; 0 when off. |
dayStartHour() |
Day starts at, 0–6. |
logPath(date) |
The path of that day's log file, whether or not it exists; null with no log folder or a bad date. |
getDay(date) |
{ date, path, goalMinutes, focusSeconds, sessions }. goalMinutes is the setting for today and later, and for an earlier day the goal its file recorded (or null). path is null when the day has no file. focusSeconds counts as the goal does, without a session still running. |
getDays(from, to) |
A getDay for each day from from to to, both included, up to 400 days. |
YYYY-MM-DD text. A bad date or range makes getDay and getDays reject.kind (focus or rest), type, task ({ name, path }), id, start, end, scheduled, total, overtime, pauses (a list of { start, end }) and status. Times are the text as written; numbers are seconds. A field the line doesn't have is null, except pauses: empty when there were none (and on Rest lines), null only when it can't be read, so check it.sessionId, startedBy, endedBy, planned, cycle, offset, endOffset (the offset when it ended), slept, dropped and device, from the fields under Log format. On a line with sessionId, a missing slept or dropped is 0. On older lines all ten are null. startedBy and endedBy may gain values in a later version.face (frown, meh, smile or null) and note (the words without the face, or null), from the focus note. Both are null on a break and on a line without sessionId.?.api is undefined when it's off), and its members keep their meaning while version stays the same.Open viewStart / Pause / Finish & next / Skip to nextOpen today's log — never creates an empty file.Check log / Convert old log lines — Check changes nothing; Convert asks first, with exact counts.Add a session / Fix a logged sessionAdd a note to the last session — only while Offer a focus note is on. Works with the timer panel closed.Export sessionsRefresh log task names by IDShow in status bar / Hide from status barCheck for misplaced pomodoro count markers / Repair misplaced pomodoro count markers / Remove misplaced pomodoro count markers / Remove all pomodoro count markers🆔 is renamed, its past lines in that folder take the new name.Note field on that session's line, in the file it was logged to. The words you haven't saved stay on this device. Changing one in Fix a logged session is an ordinary fix of that line.Nothing here leaves your device. The only network use is YouTube, below.
Timers, logs and sounds are all local. The optional lofi music is the only part that uses the network, only to YouTube, and only after 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, which loads content from YouTube/Google servers. This happens only while the timer panel is open. Clearing the link or turning the player off stops it.
Checking a link. When you paste or edit a link in the settings, the plugin sends one small request to www.youtube-nocookie.com/oembed, shortly after you stop typing, with only the video or playlist ID. It tells you if YouTube can't find the link and suggests a name. This happens even with the timer panel closed and the player off. Nothing is sent for an empty slot, a link YouTube confirms isn't checked again in the same session, and a link it can't find is checked again at most once a minute.
YouTube's handling of both is covered by Google's privacy policy.
Found a bug or have an idea? Please open an issue on the GitHub issue tracker.
npm install
npm run dev # rollup --watch (rebuilds main.js)
npm run build # one-shot production build
npm test # vitest
npm run typecheck # tsc --noEmit
npm run lint
npm run format # prettier --write .
CI runs typecheck, lint, format check, tests and build on pushes and pull requests to main. A release tag publishes main.js, manifest.json and styles.css to GitHub Releases.
Parts of this plugin were developed with AI assistance (Codex, Gemini, Claude). All code reviewed and tested by the maintainer before release.