Gentle Pomodoro

pending

by JamStudio

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

★ 2 starsUpdated 2mo agoMITDiscovered via Obsidian Unofficial Plugins
View on GitHub

Gentle Pomodoro for Obsidian

A visually soothing, task-integrated Pomodoro timer for Obsidian.

This plugin is designed to help you maintain focus while keeping track of your work directly within your vault. It features a gentle, ambient visual timer that transitions from day to night, integrates with Tasks-style checkboxes (including optional Task IDs), provides a compact status bar indicator, and automatically logs your sessions for review.

Features

🍅 Visual Timer

  • Ambient Visuals: Instead of a ticking clock, a soothing shape gently pulses and transitions colors (Day → Dusk → Night) as time progresses.
  • Focus & Rest Modes: Customizable durations for work and breaks.
  • Audio Cues: Game-ambient, gentle sounds for starting focus (War Drum) and finishing sessions (Bell/Ding).
  • Overtime Tracking: The timer counts up after the session ends, glowing gently to let you know you're in overtime without breaking your flow.

✅ Task Integration

  • Seamless Workflow: Select tasks directly from your Markdown files (compatible with the Tasks plugin format).
  • Smart Filtering: Finds tasks with scheduled or due dates and groups them as Overdue, Today, Tomorrow, or upcoming (next 3 days).
  • Context: Links your focus session to the specific file where the task lives.
  • Quick Unlink: One-click “Unlink Current Task” to clear the active task.

📊 Automated Logging

  • Daily Logs: Automatically generates a daily log file (e.g., 2025-12-23-gentle-pomodoro-log.md). Logging is disabled if no log folder is set.
  • Dataview Compatible: Logs are written in a format easily queried by the Dataview plugin.
  • Detailed Metrics: Tracks start/end times, pauses, scheduled duration, actual duration, status, and links back to the task (plus optional Task ID).
  • Rename-Safe (with ID): If tasks include 🆔, the current session updates on rename and you can refresh past logs by ID.

🧭 Status Bar

  • Compact Indicator: Shows the current mode, optional time left, and total focus time today.
  • Theme-Matched Dot: Focus uses the day theme, rest uses the night theme.
  • Click Actions: Click the dot to open the view; click the label to show/hide time left (default hidden).

Compatible Plugins

This plugin is designed to work seamlessly with other powerful Obsidian tools:

  • Tasks: Gentle Pomodoro can read tasks formatted by the Tasks plugin (e.g., - [ ] Task ⏳ 2025-12-23 🆔 abc123). This allows you to select your daily to-dos directly inside the timer view.
  • Dataview: The logs generated by this plugin use inline fields (e.g., Start:: ..., Total:: ...), making it incredibly easy to build custom dashboards and reports on your productivity using Dataview queries.

Installation

Option 1: Via BRAT (Recommended for Beta)

This plugin is currently in Beta. The easiest way to install it is using the BRAT plugin.

  1. Install BRAT from the Obsidian Community Plugins list.
  2. Open BRAT settings and click "Add Beta plugin".
  3. Paste this repository URL: https://github.com/JamieStudio-lab/obsidian-gentlepomodoro
  4. Click Add Plugin.
  5. Enable "Gentle Pomodoro" in your Community Plugins list.

View the latest release (0.0.3)

Option 2: Manual Installation

  1. Download obsidian-gentlepomodoro.zip from the Latest Release.
  2. Extract the zip file into your vault's .obsidian/plugins/ directory.
  3. Reload Obsidian and enable the plugin.

Usage

1. The Timer View

Open the timer by clicking the Clock Icon in the ribbon or running the command Open view.

2. Selecting a Task

Click the "Select a task..." button at the bottom of the timer view. The plugin scans your vault (or a specific folder you configure) for tasks formatted like this:

- [ ] My important task ⏳ 2025-12-23 📅 2025-12-25 🆔 abc123

Clicking a task links your current timer session to that specific item. If a task includes 🆔, logs can be updated by ID even after renaming.

3. Logging

Once a session finishes (or is cancelled), a log entry is appended to your daily log file.

Example Log Output:

- 🍅 Focus | Task:: [[Projects/MyProject.md|Write Documentation #docs]] | ID:: abcd12 | Start:: 2025-12-23 10:00:00 | End:: 2025-12-23 10:25:00 | Scheduled:: 1500 | Pauses:: [] | Total:: 1500 | Status:: finished
- ☕ Rest | Start:: 2025-12-23 10:25:00 | End:: 2025-12-23 10:30:00 | Scheduled:: 300 | Total:: 300

Commands

Command visibility mirrors the button logic in the view (e.g., Start/Pause/Finish appear only when relevant).

  • Open view
  • Start
  • Pause
  • Finish & Next
  • Skip to next
  • Refresh log task names by ID
  • Gentle Pomodoro: Show status bar
  • Gentle Pomodoro: Hide status bar

Configuration

Go to Settings > Gentle Pomodoro to configure:

  • Tasks Folder Path: Limit task search to a specific folder (e.g., Daily Notes or Projects).
  • Pomodoro Logs Folder: Choose where to save the daily log files (e.g., Pomodoro_logs).
  • Auto-open on startup: Open the view when Obsidian starts.
  • Show status bar: Toggle the compact status indicator.

In the Gentle Pomodoro view (gear icon):

  • Focus/Break Duration: Set your preferred minutes.
  • Sound: Toggle notification sounds.

Tip: Click the status bar label to show/hide time left (default hidden).

Development

This project uses TypeScript.

  1. npm install to install dependencies.
  2. npm run dev to start compilation in watch mode.
  3. npm run build to build the plugin for production.

Credits

AI Disclaimer

Parts of this plugin were developed with assistance from AI models (including Codex and Gemini 3 Pro). All code has been reviewed and tested by the maintainer before release.

License

MIT

For plugin developers

Search results and similarity scores are powered by semantic analysis of your plugin's README. If your plugin isn't appearing for searches you'd expect, try updating your README to clearly describe your plugin's purpose, features, and use cases.